`.
Variable image data is not supported by the Document Converter in the general case.
---
## Monitor the service
The Conversion Service provides [service logs](service-log.mdx) to monitor the status and performance of the service.
You can also use the Conversion Service Configurator to supervise document processsing via **[Health & activity](health-activity.mdx)** and **[Statistics](statistics.mdx)** tabs.
---
## Health & Activity
import useBaseUrl from '@docusaurus/useBaseUrl';
The state and recent activity of the service is monitored by the Health and activity tab of the the Conversion Service Configurator GUI, which is added to the Windows start menu during installation.
The purpose is to provide an overview of the service's performance. It consists of the following parts:
- The number of jobs that the service is currently processing
- Time passed since when the service was started
- Validity of the license
- Pie chart about the results of the jobs processed on the current day
- Time chart tracking the service's load and performance
## Jobs, tasks, and parallel execution
A job is the unit that is sent to and processed by the Conversion Service. A job consists of input documents, a workflow name, a profile name, and an output path.
Depending on the job content, a set of processing steps is required to complete its execution (such as destructuring, conversion, merging, etc). A task is the execution unit of such a processing step. Tasks are generally executed in parallel and tasks are held in a queue in case the service is charged to capacity.
The parallel processing capacity of the service depends on the license and the underlying hardware system. The license and hardware limit the number of tasks that can be processed in parallel by the service. This number is referred to as the maximum number of concurrent tasks (*maxConcurrentTasks*).
### Status
Summarizes the status of the Conversion Service by displaying the count of currently processed jobs, status of the license, and service uptime.
### Processed jobs
The pie chart summarizes and monitors jobs processed during the current day in the following categories:
- **Jobs successful**: Jobs converted successfully.
- **Jobs with warnings**: Jobs converted with warnings.
- **Jobs failed**: Jobs that failed with errors related to the input document. For example, *Corrupt*, *UnsupportedFormat* or *Generic*.
- **Jobs with errors**: Jobs that failed due to a *Timeout*, *Configuration* or *Internal* error.
- **Jobs canceled**: Jobs that where canceled by the user.
### Activity
The time chart gives an indication on the service's load and performance. It displays the following two curves, which are limited by the parallel processing capacity of the service:
- **Utilization** (green): Plots the percentage of processing capability used. The total possible processing capability of the service depends on your license and your system.
- **Number of tasks in queue** (yellow): Shows the number of tasks are waiting in the queue for being processed.
On top of the diagram, on the very right, there are four numbers, each next to a symbol. These values are in the color of the curve they are associated with. The top green value is the maximum. The bottom green value is the average of the utilization. The top yellow value is the maximum number of tasks in queue for the selected time span. The bottom yellow value is the average time a task spends waiting in the queue before being processed.
Next to the Activity heading, the following time spans can be configured for the chart:
- Last ten minutes
- Last hour
- Last two hours
- Last four hours
When you change the selected item in the legend at the bottom of the chart, the curve it represents is brought to the foreground together with its associated grid for easier reading.
Note that for the Y-axis, the range of values is labeled at the right-hand side.
---
## Service log
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
The Conversion Service writes verbose information to a log file (or to the standard output in the case of Docker container). This allows the administrator to monitor the service's operation and troubleshoot problems after an event.
### Location of the log file
The location of the standard log files can be configured using the [Service configuration](../configure/configure-win-service.mdx). The name of the log files is `ConversionService-Service.log`. After each day, the old log file is compressed and moved to the file `ConversionService-Service-yyyy-mm-dd.log.zip`. A maximum of 90 archived log files are kept.
The file containing all log entries is `/var/log/convsrv/ConversionService-Service.log`. This log file is primarily designed for [support issues](#creating-a-support-request-using-the-service-logs).
**Example**: See all critical errors that occurred in container `‹CONTAINER›`
```
docker exec ‹CONTAINER› grep -e ",ERROR\|FATAL," /var/log/(*@\ctxDockerFolder @*)/(*@\ctxServiceShortName @*)-Service.log
```
### Log properties
In addition to standard properties, log entries contain the following:
| Property | Description |
|---|---|
| `Level` | Severity of the message. See [Severity level](#severity-level). |
| `Process name` | The name or type of the process in which the log event occurred. |
| `Message` | The log message. |
| `Exception` | Critical log messages often have an exception associated that contains more detailed information on the message's cause. |
| `Job ID` | Using the job ID, all messages of a particular processing job can be filtered for analysis. |
| `Task ID` | This is an internal ID used by the service, which is useful for analysis by Pdftools Support team. |
| `Remote ID` | The IP address of the remote host (client). This is meaningful only for messages that are associated with a request at the REST API. |
#### Severity level
The level indicates the severity of the message. The following severities are common:
| Level | Description |
|---|---|
| `Fatal` | Severe error. See **Error** below. |
| `Error` | Error that prevents the service from operating, e.g. because of an incomplete installation or invalid configuration. Clients sending processing requests to the service receive an error code *internal* or *configuration*. It is recommended that the service administrator be notified whenever a message of severity level **Error** or higher occurs. This can be achieved by monitoring the standard service log file or creating a [custom log](#custom-logs). |
| `Warn` | Errors that are not critical and do not prevent the service from operating. Even though no immediate action by the service administrator is required, it is advisable to review warnings periodically and decide if an action is required. |
| `Info` | Informational events are useful to monitor the service's operation. |
| `Debug` | Debug and tracing messages are strictly for development purposes and analysis by the Pdftools Support team. During productive use of the service, messages of this level should be disabled for performance reasons. |
| `Trace` | See **Debug** above. |
### Reading the log file
The standard log file is in CSV format, which can be opened in several applications. Many of them offer a tabular view of CSV files, highlighting by log message severity, and filtering.
## Custom logs
For logging, the Conversion Service uses [NLog](https://nlog-project.org/), a very flexible logging platform. This allows to create additional log outputs. For example, to write to a database or the Windows Event Log.
### Layout renderers
The following additional layout renderers are available in the Conversion Service:
- `${gdc:processName}`: Process name
- `${mdlc:jobId}`: Job ID
- `${mdlc:taskId}`: Task ID
- `${mdlc:remote-ip}`: Remote IP
For more information on these properties, see [Log properties](#log-properties).
#### Examples of layout renderers
To add a new log output, a file `NLog.config` can be created in the directory `bin` of the installation directory. For more information, see [NLog](https://nlog-project.org/) documentation.
:::note
A new logging configuration can be tested by disabling the Conversion Service's license in the license manager. When the service is restarted and a job scheduled, an error is logged.
More information on logging configuration issues can be obtained by activating internal logging:
```xml
```
**Example**: A `NLog.config` that writes critical messages to the Windows Event Log
```xml
```
**Example**: A `NLog.config` that sends critical messages by email
```xml
```
For logging, the Conversion Service uses [NLog](https://nlog-project.org/), a very flexible logging platform. This allows to create additional log outputs. For example, to write to Amazon CloudWatch or Google Cloud Platform Logs.
## Creating a support request using the service logs
When you create a support request, you need to provide Pdftools Support with information to effectively evaluate and troubleshoot your support case.
You can automatically export the service logs and other information using the Configurator. The **Support Request** tab in the Configurator lets you generate a ZIP file ("SupportRequestFiles") in your local machine that you can attach to your support request. The ZIP file contains data such as active workflows, jobs recently performed by the service, service log files, and service debug log files that help us to identify the origin of your issue, and perform troubleshooting.
To generate the ZIP file with all the required information, activate the **Support Data** toggle.
To include information about the security policy of users and groups which helps to identify Microsoft Office related issues, activate the **Extended Support Data** toggle.
You can also choose to share analytics to help improve the product. Pdftools does not track any of the data of your Conversion Service implementation. Analytics are only used for the purposes of improving your experience with the Conversion Service. The exported analytics ZIP file contains statistics on the workflows and profiles used, the number of output files and their size, and the number of pages in each output file. No information that can be used to identify the contents of the documents you process is collected. All analytics are stored in your local machine.
You can choose to include analytics data when you create the ZIP file for your support request by activating the **Analytics data** toggle.
When you click **Export**, a window opens where you can choose where to save the exported file. You must attach this file to your support request.
### Support Data Collection
We collect specific data from your system to help us diagnose and address your issues more effectively. This collection is vital for us to provide you with the best possible support. Our commitment is to maintain transparency with our enterprise clients about the data we access.
**Data We Collect:**
1. **Event Logs in the Last 24h**: This helps us understand any recent system or application events that might have contributed to the issue you're facing.
2. **Software Versions**:
- **Conversion Service**: Helps us determine if any known issues exist with your current version.
- **Office**: Assists in diagnosing potential compatibility or integration issues.
3. **Win32 Tables**:
- **UserAccount, LogonSession, LoggedOnUser**: Provides insights into user accounts, their sessions, and logon activities.
- **Group, GroupUser**: Details about user groups and their members that are necessary for understanding access and permissions. The Conversion Service collects this data only if you enable the **Extended Support Data** toggle.
- **Service**: Information about running services, which can highlight conflicts or dependencies.
- **Printer, PrinterDriver**: Essential for understanding the PDF generation process. When creating PDFs from Excel spreadsheets, Excel uses the Windows printing system, making printer settings and drivers crucial for successful conversion.
- **QuickFixEngineering**: Information on recent patches or fixes applied to the system.
- **GPO Information**: Extracts rights for all Users and Groups, assisting in understanding policy-related issues.
- **OperatingSystem**: Details of the OS, which can help in understanding compatibility or known issues.
- **ComputerSystem**: Information about the computer's hardware and configuration.
- **Processor**: Helps diagnose performance or compatibility issues.
- **LogicalDisk**: Information on storage, which can aid in understanding space-related issues.
- **DCOMApplication, DCOMApplicationSetting**: Provides insights into distributed component settings and potential conflicts.
4. **Conversion Service Product Configuration**:
- **appsettings.json**: Configuration settings that might be causing issues.
- **Workflows.xml**: Workflow configurations that could lead to operational problems.
- **Backups of old Workflows.xml**: Historical configurations to compare and trace the origin of issues.
5. **Log Files (from the Conversion Service)**: Detailed logs can highlight errors, warnings, or unusual behaviors.
6. **Report Files (from the Conversion Service)**: Generated reports can provide context on the tasks or processes that were running when an issue occurred.
All the data collected is strictly used for support and diagnostic purposes. We ensure that every piece of information is treated with the highest standards of confidentiality and security. Transmitting this data allows our support team to understand the context better and pinpoint the root causes of issues, ensuring efficient resolution.
We understand and respect the importance of your data's privacy and integrity. All data is securely transmitted, and we adhere to rigorous data protection standards to ensure the safety of your information.
For any concerns or further questions about our data collection practices, please contact our support team or review our comprehensive privacy policy.
---
## Statistics
Information about the past activity of the service is reported by the Statistics tab of the the Conversion Service Configurator GUI, which is added to the Windows start menu during installation.
With this tab, the conversion history of the service can be analyzed. The Statistics tab consists of the following parts:
- [Filters](#filter-section): A section containing a set of filters to control the data displayed in the tab.
- [Simple statistics](#simple-statistics): An overview displaying the performance of the service.
- [Processed jobs](#processed-jobs): Pie chart about the results of the processed jobs.
- [Activity](#activity): Time chart indicating service's load and performance for a selected group of jobs.
In addition, the data displayed in the tab can be exported for further analysis.
## Filter section
In the top row of the tab, below the title, the following filters can be configured to be applied to the data displayed in the tab:
**Time unit & period**
Determines the period of time when the jobs were processed. On the left-hand side, the length of the period can be configured by selecting one of the following time units:
- Day
- Week
- Month
On the right-hand side, the point of time where the period occurred can be selected either by clicking on the calendar icon and choosing it from the calendar dropdown which has appeared or by clicking the arrows.
**Workflows**
Filter data to show usage, load ,and job results of specific workflows.
**Query time**
The time point when the query for the displayed data was made. The query time is only relevant if the current day is part of the selected time period. The query time can be updated with the refresh icon in this case.
## Export data as CSV
Click **Export Data as CSV** in the top-right menu to export the data selected by the filters from the database.
When the export has finished, a ZIP archive containing the following CSV files is saved:
`service.csv` contains the following columns:
- `started`: Service start time.
- `stopped`: Service stop time.
- `maxConcurrentTasks`: Concurrency supported by the license, i.e. the maximum number of tasks which can be executed in parallel. For more information, see [Health & Activity](health-activity.mdx).
`jobs.csv` contains the following columns:
- `id`: Row number.
- `jobId`: Unique identifier name of the job.
- `worklow`: Name of the workflow the job was processed with.
- `profile`: Name of the profile the job was processed with.
- `started`: Point in time when the service started to process the job.
- `finished`: Point in time when the service completed the job.
- `error`: Name of the error if the job failed.
- `warnings`: List of the names of the warnings that occurred when processing the job.
- `outputFilesCount`: Total number of output files resulting from the conversion.
- `overallOutputSize`: Total number of bytes summed over all output files resulting from the conversion.
- `overallPages`: Total count of pages summed over all output files resulting from the conversion.
`tasks.csv` contains the following columns:
- `id`: Row number.
- `job`: Row number of the job the task is associated with tasks.
- `queued`: Point in time when the task began waiting in the queue for being processed.
- `started`: Point in time when the task moved out of the queue and the service started to process it.
- `stopped`: Point in time when the service was finished with processing the task.
- `component`: Names the type of processing step applied through this task.
## Simple statistics
Displays some characteristic numbers about the jobs considered by the current filter configuration and the service:
- **Service uptime**: The total amount of time that the service has been running.
- **Processed jobs**: The total number of jobs that have been processed.
- **Processed pages**: The total sum of pages of documents converted to PDF.
- **Processing time**: The total sum of job processing time. Note that this number can be higher than *Service Uptime* since multiple tasks can be processed in parallel.
- **Output file size**: The total sum of output file size of the processed documents.
## Processed jobs
The pie chart summarizes the jobs considered by the current filter configuration in the following categories:
- **Jobs successful**: Jobs converted successfully.
- **Jobs with warnings**: Jobs converted with warnings.
- **Jobs failed**: Jobs that failed with errors related to the input document like for example *Corrupt*, *UnsupportedFormat* or *Generic*.
- **Jobs with errors**: Jobs that failed due to a *Timeout*, *Configuration* or *Internal* error.
- **Jobs canceled**: Jobs that where canceled by the user.
## Activity
The time chart indicates the service's load and performance. The filters apply to this diagram as well. It displays the following two curves:
- **Utilization** (green): Plots the percentage of processing capability used. The total possible processing capability of the service depends on your license and your system.
- **Number of tasks in queue** (yellow): Shows the number of tasks are waiting in the queue for being processed.
On top of the diagram, on the very right, there are four numbers, each next to a symbol. These values are in the color of the curve they are associated with. The top green value is the maximum. The bottom green value is the average of the utilization. The top yellow value is the maximum number of tasks in queue for the selected period. The bottom yellow value is the average time a task spends waiting in the queue before being processed.
When you change the selected item in the legend at the bottom of the chart, the curve it represents is brought to the foreground together with its associated grid for easier reading.
Note that for the Y-axis, the range of values is labeled at the right-hand side.
---
## Conversion Service release notes
import useBaseUrl from '@docusaurus/useBaseUrl';
Review what's new in the Conversion Service. These release notes provide the latest functional changes, additions, and selected bug fixes or performance improvements.
:::tip
To update to the latest version, see **[Update the Conversion Service](./update/README.mdx)**.
:::
---
## Version 6
The following sections provide updates in version 6 of the Conversion Service.
### 6.6.0
28 October 2025
#### Added
- As of this release, your page credits consumption under the **License** tab in the Conversion Service Configurator.
- Added **Gmail connectors** for integration with Gmail accounts. The new connectors include:
- **Watched Mailbox (Gmail)**: Input connectors that convert emails from Gmail mailboxes.
- **Output Mailbox (Gmail)**: Output connectors that copy processed files to Gmail mailboxes.
- **Send Email (Gmail)**: Email sending connectors that send notifications and results through Gmail SMTP server.
Each Gmail connector type supports two authentication methods:
- **App Passwords**: Authenticate using Gmail App Passwords, which requires 2-step verification.
- **OAuth 2.0**: Authenticate using your organization’s OAuth credentials from Google Cloud Console. Provides organization-level control over email access, independent credential management, and dedicated rate limits that are separate from those of other users.
All of these connectors include IMAP/SMTP settings optimized for Gmail. For more information, review [Gmail connectors](/docs/conversion-service/integrate/connectors/email-connectors/#watched-mailbox-gmail) documentation.
- You can now extract property values generated through the workflow components and use them where available with the placeholder syntax.
- The Dossier workflow now lets you configure PDF annotations that can be positioned on PDF dossier pages and table of contents pages.
#### Fixed
- Fixed an issue with widget annotation text not present in the output after PDF/A conversion.
- The MSG files attached to emails have properly rendered characters.
- The license agreement has been updated to the new terms and conditions.
### 6.5.0
17 September 2025
#### Added
- Added a new **Output File Settings** section in the [Dossier](./workflows/dossier.mdx) workflow configuration, introducing configurable attributes for invalid filename characters and maximum filename length.
- As of this release, you can now convert JPEG File Interchange Format (JFIF) images to PDF. The JFIF conversion to PDF is included in the following workflow profiles:
- [Conversion](./workflows/conversion.mdx)
- [Archive PDF/A-2](./workflows/pdfa_2.mdx)
- [Archive PDF/A-3](./workflows/pdfa_3.mdx)
- [Archive PDF/A-1](./workflows/pdfa_1.mdx)
- [Archive TIFF](./workflows/tiff.mdx)
- As of this release, you can linearize PDF documents during the conversion process. This will create a PDF document that is optimized for fast web viewing. Linearization is available in the following workflow profiles:
- [Conversion](./workflows/conversion.mdx)
- [Archive PDF/A-2](./workflows/pdfa_2.mdx)
- [Archive PDF/A-3](./workflows/pdfa_3.mdx)
- [Archive PDF/A-1](./workflows/pdfa_1.mdx)
#### Fixed
- Fixed an issue with a multi-level table of contents creation in the Dossier workflow that failed under certain conditions. For more information, review [Dossier](./workflows/dossier.mdx) documentation.
### 6.4.2
4 September 2025
#### Fixed
- The License Gateway Service (LGS) mode in the Conversion Service Configurator is now automatically refreshed. There are two available modes, [Connected mode](/docs/licenses/configure/licensing-gateway-service/) and [Full offline mode](/docs/licenses/configure/offline-licensing-gateway-service/).
- Fixed an issue where `.msg` files containing non-Latin characters could render incorrectly during conversion. This release resolves the issue by improving the font matching logic to resolve font table selection correctly.
### 6.4.1
7 August 2025
#### Fixed
- Fixed stack corruption when creating an annotation appearance. This issue led the workers to a crash and fail conversion with an `EndOfStreamException` error.
### 6.4.0
30 July 2025
#### Added
- As of this release, you can use the Pdftools OCR Service with the Conversion Service. This OCR configuration is compatible with the legacy 3-Heights® OCR Service and doesn't require any additional configuration for users who have already integrated the legacy OCR. Review [Pdftools OCR Service](/docs/ocr-service/) documentation for setup and configuration details.
- You can now choose to hide the default header that is added when converting emails to PDF.
#### Changed
- The **Header time format** subsection was renamed to **Header** in the **Email Settings** configuration section.
- In the workflow and profile configuration, the **3-Heights® OCR Service** engine was renamed to **Pdftools OCR Service (3H Legacy Compatible)**.
### 6.3.0
24 June 2025
#### Added
- You can now add annotations to PDF documents. Annotation can be moved, resized, or removed in a viewer where a user can edit the PDF. Review [Stamp and annotation](./configure/configure-stamping.mdx) documentation for configuration details and more information.
- With this update, you can set up a fallback time-stamp authority (TSA) in the Conversion Service Configurator. As a result, you can add a backup TSA URL that the Conversion Service will use if the primary TSA isn't available.
#### Changed
- The following changes were made in the Conversion Service Configurator.
- The **Document Optimization** processing step (included in all PDF/A workflows) was renamed to **Compression and Optimization**.
- The **Stamping** processing step was renamed to **Stamp and Annotation**.
- The **Warnings** configuration section was renamed to **Events**. Previously, this configuration section name was the same as one of its main contents (which are warning, error, ignore). The **Events** configuration section lets you configure which issues detected during the workflow processing are only logged as a warning, ignored, or stop the processing with an error.
#### Fixed
- Fixed an issue where the **Event Date** in MSG files was not serialized correctly.
- Resolved an error that occurred when converting EML files in **Collect Mode** was set to **Separate for Job** in the **Conversion** workflow.
### 6.2.0
23 May 2025
#### Added
- As of this update, you can use the Licensing Gateway Service (LGS) in the full offline mode with the Conversion Service. For more information, review [Full offline mode](/docs/licenses/configure/offline-licensing-gateway-service/) documentation.
- With this update, you can now use a new accessibility workflow designed to validate PDF compliance with accessibility standards, including **PDF/UA (ISO 14289)**, **Web Content Accessibility Guidelines 2.1 (WCAG)**, and general **quality guidelines**. For more information, review [Accessibility workflow](./workflows/accessibility.mdx).
- You can now import and export profiles in the Configurator Web (beta). Making it easier to share and manage profiles across different instances of the Conversion Service. For more details, review the [Configure profiles using Configurator Web](./configure/configure-profiles-docker.mdx#configure-profiles-using-configurator-web) section.
#### Changed
- We have removed the `latest` tag from the Conversion Service Docker images to align with Docker best practices and improve version traceability. As a result, when using the `docker run` command, Docker Compose YAML files, or any other Docker configuration files, the `image: pdftoolsag/conversion-service:` can no longer set to the `latest`, but only to specific versions, such as `6.2.0`, `6.2`, `6`. Please make sure you reference specific version tags when pulling Docker images.
### 6.1.0
14 April 2025
#### Added
- As of this release, the Conversion Service offers more predefined input connectors for new users upon installation. These connectors leverage the Simple API and highlight the most commonly used workflow profiles. When the Conversion Service is running locally or on an IP address that you specify in the `baseURL`, you can test these connectors using the [Simple API Postman collection](pathname:///files/conversion-service/conversion_service_simple_api.postman_collection.json) or the [Simple API reference](./api/simple-api/simple-api.info.mdx).
The Conversion Service Configurator doesn't display the updated connectors for users who already have the Conversion Service installed. To access the new connectors, uninstall the Conversion Service, delete the associated configuration files from the installation folder, and then reinstall the Conversion Service. This process was implemented to avoid confusion for users who have already configured their connectors.
Although the Postman collection has been updated, you can still access the previous default Simple API endpoints from the legacy folder. Additionally, the previous default PDF/A-2 REST input (plain HTTP) and PDF/A-2 input JSON connectors remain compatible and are located in the **Archive PDF/A-2** folder in the Postman collection.
- You can now configure Microsoft Office file conversion in the Configurator Web (beta), alternative to the Conversion Service Configurator that lets Docker users change the Conversion Service configuration without the need of exporting files from a Windows Server machine. The Configurator Web is still in beta and does not yet support all the capabilities of the Windows-based Conversion Service Configurator. For more details, see the [Configure profiles using Configurator Web](./configure/configure-profiles-docker.mdx#configure-profiles-using-configurator-web) section.
#### Changed
- Previously, the LGS only gathered data about the number of pages processed by the Conversion Service. As of this release, LGS also collects and reports the number of pages processed using a specific Conversion Service workflow. As a result, both the number of pages processed (volume) and the workflow which was used by the Conversion Service is reported through the LGS.
#### Fixed
- Improved configuration validation for Send Email (SMTP) and Send Email (Exchange Online) output connectors. With this release, the Conversion Service Configurator prevents invalid configurations where a job status is set to **Error** and **Attachments** is set to **Result Files**. This validation prevents potential issues since error jobs don't produce any result files to attach.
- Prior to this release, the **Allow Resize PDF** feature did not correctly handle landscape-oriented documents, causing unexpected rotation to portrait format and loss of redactions after conversion, leading to formatting issues. As of this release, a new resize-tolerance property was introduced to provide configurable control over resizing behavior. As a result, landscape orientation and redactions are preserved, and resizing can be fine-tuned based on specific requirements.
- Previously, a refactoring of the Docker image caused profile import to fail in the Conversion Service container, resulting in a startup error when accessing `Workflows.xml`. This release fixes the issue by adjusting the Docker image, and profile import now works as expected during container startup.
### 6.0.0
3 March 2025
#### Added
- As of this update, you can set up Conversion Service profiles and workflows in Docker, enhancing the experience for Docker users. You no longer need to install the Configurator on a Windows Server machine to export configuration files to your Docker instances. The first version of the Configurator Web is still in beta and does not yet support all the capabilities of the Windows-based Conversion Service Configurator. For more details, see the [Configure profiles using Configurator Web](./configure/configure-profiles-docker.mdx#configure-profiles-using-configurator-web) section.
- You can now learn how to integrate the Conversion Service using OpenShift with a [Conversion Service on OpenShift](./configure/configure-openshift.mdx) guide.
- With this update, you can use the same license key with unlimited number of LGS instances used with the Conversion Service.
#### Changed
- As of this version, you no longer need to use the `msiexec /i ConversionService-VERSION_NUMBER.msi PDF_TOOLS_DISABLE_OS_CHECK=1` command to enable installation of the Conversion Service on regular Windows machines. This makes the installation process simpler and more straightforward for evaluating users and for users who need to export the configuration files from regular Windows machines.
#### Fixed
- Configuration stability improvements when removing Microsoft Office users.
## Version 5
The following sections provide updates in version 5 of the Conversion Service.
### 5.7.6
24 July 2025
#### Fixed
- As of this release, lifecycle management has been added for the native error callback to prevent `EndOfStreamException` errors caused by callbacks referencing garbage-collected delegates.
### 5.7.5
28 April 2025
#### Fixed
- Prior to this release, the **Allow Resize PDF** feature did not correctly handle landscape-oriented documents, causing unexpected rotation to portrait format and loss of redactions after conversion, leading to formatting issues.
### 5.7.0
23 December 2024
#### Added
- As of this update, you can convert WebP images to PDFs.
- You can now export word track changes (redlining) to PDF. For more details, review [Configure conversion of redlined Microsoft Word documents](./configure/word-track-changes.mdx).
- Previously, you could only skip creating the table of contents in the Dossier workflow. As of this update, the Conversion Service Configurator lets you also skip the creation of outlines (bookmarks) in the Dossier workflow. To skip the outline creation, go to the Dossier workflow configuration and disable the **Outline (Bookmarks)** toggle.
When the previously described **Outline (Bookmarks)** option is enabled, the **Outline (Bookmarks)** configuration section includes the **Document Bookmark** toggle. If you disable this toggle, bookmarks from various files that are merged into a dossier are no longer nested as children but are all included at the same level.
#### Changed
- With this update, the **Troubleshooting** tab of the Conversion Service Configurator displays issues detected in profile and connector configuration validation.
- Previously, you could accidentally install the Conversion Service Client on a machine where the Conversion Service was already installed, causing the service to malfunction. As of this release, you can no longer install the Conversion Service Client when the Conversion Service is already installed on the same machine.
### 5.6.0
8 October 2024
#### Added
- You can now configure the default address of the Connector Service. For more details, review [Connector service host address](./configure/configure-win-service.mdx#https) section.
#### Changed
- Previously, the Conversion Service Configurator included separate toggles for **Add Outlines** and **Hide Outlines**. This feature is available in the Archive PDF/A-1, Archive PDF/A-2, and Archive PDF/A-3 workflows. With this update, the previously separate toggles are now moved into one dropdown menu with the following three options: **Display**, **Hide**, and **Remove**
#### Fixed
- As of this release, the conversion of HTML, XML, MSG, and EML files is improved.
### 5.5.0
29 August 2024
#### Added
- A new welcome window is displayed when you open the Conversion Service Configurator. The welcome window links to the [Getting Started](./getting-started/README.mdx) documentation, and you can disable it for the next sessions.
- With this release, you can set which files attached to emails are skipped during conversion. For more information, review the following sections of the Email connectors documentation:
- Watched Mailbox (IMAP) [Settings](./integrate/connectors/email-connectors.mdx#settings)
- Watched Mailbox (Exchange Online) [Settings](./integrate/connectors/email-connectors.mdx#settings-1)
#### Changed
- With this release, the Pdftools no longer supports Microsoft Office 2016 and Windows Server 2016 with the Conversion Service. You can still utilize the Conversion Service on Windows Server 2016 and use Microsoft Office 2016 for file conversion. However, Pdftools doesn't provide technical support for new customers who use the mentioned versions.
### 5.4.0
24 July 2024
#### Added
- Support **HTTPS** communication for [REST input JSON](./integrate/connectors/rest-connectors/rest-input-connectors.mdx#rest-input-json) and [REST input plain HTTP](./integrate/connectors/rest-connectors/rest-input-connectors.mdx#rest-input-plain-http) connectors. For details how to activate the **HTTPS** communication, review [HTTPS](./configure/configure-win-service.mdx#https) documentation.
- You can now convert HTML files containing multimedia elements that are being removed during file conversion. Previously, attempting to convert HTML files with elements such as iframes, audio, or video resulted in an error. With this update, you can set **HTML Multimedia Removed** in the **Warnings** section of the profile configuration in the Conversion Service Configurator. As a result, you can skip multimedia elements from HTML files using the described configuration.
- Set the **Allow Scaling** option for **Text Stamps** to ensure that the Conversion Service is not adding the stamp outside of the page boundaries. For more information, review [Configure stamping](./configure/configure-stamping.mdx) documentation.
- With this release, you can specify which files the Watched Folder connector skips using glob patterns. For more information, review [Configuration options](./integrate/connectors/folder-connectors.mdx#configuration-options) in the Watched Folder connector docs.
- The Conversion Service adds outlines (bookmarks) to converted PDF files by default. Previously, there was no option to disable or hide the bookmarks. As of this update, options to remove or hide bookmarks are available for the following workflows: Archive PDF/A-1, Archive PDF/A-2, Archive PDF/A-3.
- To remove the bookmarks: Disable the **Add Outlines** toggle in **Conversion Settings** > **Viewer Preferences** configuration section.
- To hide the bookmarks: Enable the **Hide Outlines** toggle in **Conversion Settings** > **Viewer Preferences** configuration section. As a result, the bookmarks are still accessible in your PDF viewer but are hidden by default.
- As of this release, you can now convert hidden attachments in emails (attachments that start with a dot). To use this feature, enable the **Include Hidden Attachments** toggle in **Email Settings** of the Configurator.
- You can now remove format protection in the Office for Web configuration. Enable the **Remove Excel Format Protection** toggle in **Office Conversion** > **Office For Web Settings** configuration section.
#### Fixed
- Under certain circumstances, conversion of .MSG file to any PDF or PDF/A format resulted in images being replaced by placeholders in the output PDF files. This issue is now fixed and all images are displayed correctly.
- Before this update, while using the Dossier Workflow, merging PDF with form fields of the same name as the PDF file overwrote the form fields. This issue is now fixed and all PDFs are displayed properly.
### 5.3.0
19 June 2024
#### Added
- Proxy settings are now extended. Email-related connectors can now use a defined proxy URL if you enable it in the Configurator. Review [Proxy](../configure/configure-win-service/#proxy) configuration documentation for more information.
- With this release, the Configurator introduces a **Troubleshooting** tab that offers solutions to detected issues. In this version, the troubleshooting functionality checks if the recommended Microsoft Defender rules are set. This feature will be expanded to include additional checks.
- Profile option **Allow Resize PDF** in **Document Settings** configuration section. This option resizes the page using the value set in the **Default Page Size** option configured in the **Document Settings** section. If you disable this option, the original page size of the document is used.
- Before this update, you could only convert email subject fields to titles during email to PDF/A conversion. With this update, you can now set the **Use Subject As Subject** configuration option in the **Email Settings** section of the Configurator that converts the subject of an email as a title and as a subject of the PDF file.
#### Fixed
- Previously, when configuring the **Child Removed** to **error** in the **Warnings** section of the profile settings, the Conversion Service prompted you with a warning instead of an error when removing the child files (files attached to emails or other document formats). With this update, the issue is fixed, and the configuration results in an appropriate error prompt when the Conversion Service removes child files in the described configuration.
### 5.2.0
9 May 2024
#### Added
- Workflow **Archive TIFF**. For more information, see [Archive TIFF workflow](./workflows/tiff.mdx) documentation.
- Workflow **Sign**. For more information, see [Sign workflow](./workflows/sign.mdx) documentation.
- New functionality to activate, update, and deactivate core-based license keys offline using the License tab within the Configurator. For more information, see [Legacy core-based license key](../../licenses/products/conversion-service-license/#legacy-core-based-license-key).
### 5.1.0
3 April 2024
#### Added
- Profile option **Include external images** in **Document Settings** configuration section. For more information, review the [Configure output file appearance](/conversion-service/configure/configure-emails/#configure-output-file-appearance) section in the Configure email processing documentation.
- An error code `external` in the REST interface for issues that can occur while trying to use an external service or load an external resource.
- Conversion Service now supports Docker Compose. The Docker Compose lets you use the REST connectors, Watched Folder connector, and seamlessly update to a new version. For more information, see [Set up the service in Docker](./configure/configure-docker-container.mdx).
### 5.0.0
29 February 2024
#### Added
- The Archive PDF/A-3 workflow now has a new profile option **Flatten annotations** in section **Document Optimization**.
- In the Configurator, you can now enable the Licensing Gateway Service on another machine by changing the license gateway address. For more details, see [Conversion Service licensing](/docs/licenses/products/conversion-service-license/) documentation.
#### Changed
- Dependency on Microsoft .NET Desktop Runtime 8.0 (Windows, x64) and Microsoft ASP.NET Core Runtime 8.0 (Windows, x64).
## Version 4
The following sections provide updates in version 4 of the Conversion Service.
### 4.8.0
4 December 2023
#### Changed
- Disabled office conversion for the integrated default workflow profiles in Docker.
- Support workflow options for the REST input plain HTTP connector using placeholder syntax. Note: An update to version 4.8 may break the file processing due to breaking changes. Previously, all the query parameters were set as variables. With this update, you have to define the variables in the Configurator. For more information, see [REST input plain HTTP](./integrate/connectors/rest-connectors/rest-input-connectors.mdx#rest-input-plain-http) in the REST connectors documentation page.
### 4.7.0
25 September 2023
#### Added
- Support for consumption-based licensing.
- As of this update, the Licensing Gateway Service is installed by default with the Conversion Service.
- Configuration setting to set up custom job options.
- The Configurator now includes a new tab **Licensing** for license management that can replace the separate license manager in most cases in the Conversion Service Configurator.
#### Fixed
- Improved support request. Added additional data for better insight in the Configurator.
### 4.6.0
26 July 2023
#### Added
- Customization of email header date time formatting.
### 4.5.0
28 June 2023
#### Fixed
- Improved conversion of email body and HTML documents.
- Improved compatibility of mailbox connectors with Microsoft Exchange.
### 4.4.0
31 May 2023
#### Added
- Enable export of analytics and redesign of Support tab.
### 4.3.0
3 May 2023
#### Added
- As of this update, you can use new stamping functionality that allows page selection - All, First, and Last.
- The **Collect Mode** setting **Separate** to convert a job with multiple files into separate output documents instead of a single output.
- Configuration setting to preserve the body of the corresponding input email when used with result files.
- Swisscom on-demand signature.
- Allow job options for certain signature properties.
#### Changed
- Changed digital signature types to have a simpler overview.
- Swisscom signature types were renamed to remove **All-in** from the signature type name.
#### Fixed
- Improved conversion of emails with non-standard structure.
- Improved reliability and robustness of Office conversion.
- Fix configuration updater to reflect new Swisscom signature type names. [patch v4.3.2]
### 4.2.0
30 March 2023
#### Added
- Support for CSV files with whitespace around quoted fields without warning or error.
- Detailed information for the Health & Activity, Services, and Statistics tabs are displayed in the documentation panel.
#### Changed
- Behavior for CSV files containing malformed data: CSV file containing malformed data now results in a configurable warning of type `CorruptionRepaired` instead of a hard error.
#### Fixed
- Improved UI design of the documentation panel.
### 4.1.0
17 February 2023
#### Added
- With this update, Conversion Service supports download of external stylesheets in HTML, and XML file formats through a proxy.
- Configuration option to specify the form field name of the files in the `multipart/form-data` content.
### 4.0.0
22 December 2022
#### Added
- Settings for email, HTML, CSV, and XML conversion to control resizing and optimal fitting of content in case of content overflow.
- Settings for Excel conversion to control resizing and optimal fitting of content in case of content overflow.
#### Changed
- As of this update, the default installation directory on Windows is `C:\Program Files\Pdftools\Conversion Service`.
- With this update, the default program data directory on Windows is changed to `C:\ProgramData\Pdftools\Conversion Service`.
## Version 3
The following sections provide updates in version 3 of the Conversion Service.
### 3.11.0
15 December 2022
#### Added
- Both Archive PDF/A-2 workflow and PDF/A-3 workflow lets you use a stamping functionality to add an image or 1D/2D barcode to the converted documents.
- Dossier workflow Stamping functionality to add an image or 1D/2D barcode to the converted documents.
### 3.10.0
12 October 2022
#### Added
- Option to convert Word, Excel, PowerPoint documents through the Azure cloud with the Microsoft Office for the web service.
- Watched Folder connector received now supports companion files to pass information as variables directly to the output connectors.
- Rest output connector received the following additions:
- Support for sending form fields in addition to the files.
- Support for username/password based authentication.
- Support for setting the Accept header.
### 3.9.0
17 August 2022
#### Added
- REST interface property `Status` in result of method `getJobResult` to get Success or Warning or Error status of job result instead of using legacy `Success` property.
### 3.8.0
27 June 2022
#### Fixed
- Improved robustness in low memory conditions on Windows.
### 3.7.0
2 June 2022
#### Added
- New dependency on Microsoft .NET Desktop Runtime 6.0 (Windows, x64) and Microsoft ASP.NET Core Runtime 6.0 (Windows, x64).
#### Fixed
- Improved performance especially for small files.
### 3.6.0
3 May 2022
#### Added
- Output connector **Send Email (SMTP)** to send an email to a configurable or dynamic email address, containing the results or original files or additional information (error message, warnings).
- Output connector **Send Email (Exchange Online)** to send an email to a configurable or dynamic email address, containing the results or original files or additional information (error message, warnings).
- Output connector **Create Text File** to create a text file with additional information (error message, warnings) in an output folder.
### 3.5.0
4 April 2022
#### Added
- Profile settings and options in all workflows to add metadata to the documents.
- Input connector **Watched Mailbox (Exchange Online)** to automatically convert emails or files sent to a configurable mailbox on a Microsoft Exchange Online server.
- Output connector **Output Mailbox (Exchange Online)** to copy output files to a mailbox without actually sending an email.
### 3.4.0
23 February 2022
#### Added
- REST interface now includes query parameter `url` on `addData` POST request to load a file directly from a webserver.
- The REST interface method `storeJobResultData` to send the result file directly to a webserver via HTTP PUT/POST request.
- Stamping functionality to add single-line text content to the converted documents.
- Dossier workflow supports custom placeholder variables in Text Stamps.
- Added conversion of signed Emails (s/mime).
- You can now convert the OpenDocument Text (`.odt`), Spreadsheet (`.ods`), and Presentation (`.odp`) files through Microsoft Word, Excel, and PowerPoint, respectively.
- With this update, you can use the output connector **Output Mailbox (IMAP)** to copy output files to a mailbox without actually sending an email.
- Office add-ins for Word, Outlook, Excel and PowerPoint.
### 3.3.0
1 February 2022
#### Added
- Support for Windows Server 2022.
- Support for Office 2021 (64 Bit).
- With this update, you can use **Archive PDF/A-1** workflow.
- New conversion of WordprocessingML 2003 (`.xml`) and SpreadsheetML 2003 (`.xml`) documents through Microsoft Word and Microsoft Excel, respectively.
#### Changed
- Newly created bookmarks are now closed instead of open by default.
- The Configurator now changed the export and import of profiles to also include the workflow activation state.
### 3.2.0
28 December 2021
#### Added
- With this update, you can use an input connector **Watched Mailbox (IMAP)** to automatically convert email messages or files sent to a configurable mailbox on an IMAP server.
- **Archive PDF/A-2 workflow**:
- Use convert mode configuration for child documents (attachments) for detailed configuration of documents to convert.
- Convert HTML, CSV and XML attachments. This functionality is disabled by default.
- Configure a collect mode. This mode offers a detailed configuration of how to convert documents that have attachments, specifically how to combine the converted documents and how to handle errors when processing child documents. This supersedes the configuration options **Document Collection Mode** and **Child Error Handling**.
- **Archive PDF/A-3 workflow**:
- In the convert mode settings, you can now enable **Skip** and **Skip with Warning**, which lets you choose whether an informational event or a warning is generated when skipping (removing) a child document. The new default is **Skip with Warning**. When updating an installation, the profiles' behavior is not changed.
- The **Dossier** workflow received the following additions:
- Profile setting to control the horizontal alignment (Left, Center, Right) of the title of the table of contents.
- Job option `TOC-OUTLINE-TITLE` to set the title of the bookmark for the table of contents.
- Profile setting for automatic numbering of the entries in the table of contents.
- Profile setting to apply stamps to the pages of the table of contents.
- Optional preprocessing step to convert input documents to PDF.
#### Changed
- In the Dossier workflow, the document outline has been changed to contain a bookmark for the table of contents.
### 3.1.0
26 November 2021
#### Added
- You can now activate or deactivate workflows in the [Workflows & Profiles](../workflows/) tab.
- Conversion of CSV, HTML (prepared for archiving) and XML documents.
- The REST Output connector now supports placeholder variables in URL setting.
- REST input JSON connector received the following additions:
- Key `options` in JSON format to pass job-level and document-level options to the workflow.
- Key `variables` in JSON format to pass information directly to the output connectors.
#### Changed
- In the Configurator, the **Profiles** tab was changed to **Workflows & Profiles**.
- The REST input JSON connector changed the default request body size limit from unlimited to 100 MB.
#### Fixed
- Improved UI design to provide a clear overview of the job progress and results.
## Version 2
The following sections provide updates in version 2 of the Conversion Service.
### 2.12.0
15 October 2021
#### Fixed
- The Configurator now provides greater clarity of errors and warnings, an improvided UI validation of service, profiles, and connection configuration.
### 2.11.0
21 September 2021
#### Added
- Combine multiple PDF files into one dossier with the **[Dossier](workflows/dossier.mdx)** workflow. The dossier applies headers, footers or watermarks [v2.8] and supports title page and customizable table of contents.
- **PDF to PDF/A conversion:**
- New warning types *Annotation removed* and *Multimedia removed* for events that were previously reported as *Action removed*.
- New conversion of HEIC and HEIF images.
- Configurator now includes **[Statistics](monitor/statistics.mdx)** tab to report and analyze the service's conversion history.
- New possibility to copy profiles and connections.
#### Fixed
- Improved conversion event messages to be more specific.
- **PDF to PDF/A conversion:**
- Improved detection of optimal target conformance level where the highest level is chosen that can be achieved with a perfect conversion.
### 2.10.0
4 August 2021
#### Added
- Client installer (msi).
- Tab **[Health & Activity](monitor/health-activity.mdx)** for monitoring the state and recent activity of the service.
- REST input connector for structured JSON requests.
#### Changed
- Changed trademark ™ to registered trademark ®.
#### Fixed
- Improved processing of signed PDF documents: If signatures need to be removed, their visual appearance is preserved.
### 2.9.0
4 August 2021
#### Added
- Support for HTTPS service endpoint.
- Dependency on Microsoft .NET Desktop Runtime 5.0 (Windows, x64) and Microsoft ASP.NET Core Runtime 5.0 (Windows, x64).
- REST input connector for plain HTTP requests.
- REST output connector.
- Command Excecute output connector.
### 2.8.0
16 June 2021
#### Added
- Workflow **[Conversion](workflows/conversion.mdx)** provides document conversions from multiple file formats to PDF with an emphasis on performance and document size.
- In the Archive PDF/A-2 workflow, you now can use a profile option for emails *Use subject as filename*.
### 2.7.0
12 May 2021
#### Added
- In the Archive PDF/A-2 workflow, you now can use a profile option for emails *Use subject as filename*.
- Profile option *Child error handling*.
#### Fixed
- Improved email conversion: Attachments of emails where parts of the attachment are removed during the conversion process (e.g. a not convertible part of a ZIP file) are now listed as *Partially removed* inside the email header.
- Improved UI design of the profiles tab to provide a clear overview of profiles and their related workflow.
### 2.6.0
15 April 2021
#### Added
- New `Configuration` and `Timeout` job result error codes in the REST interface.
- New support for load-balancing to multiple instances of 3-Heights® OCR Service.
#### Fixed
- Improved conversion of DOCX documents: Certain corrupt documents are now repaired automatically.
- Improved conversion of password-protected DOCX documents: Embedded files from these documents can now be processed.
### 2.5.0
16 March 2021
#### Added
- Workflow **[Archive PDF/A-3](workflows/pdfa_3.mdx)** similar to **[Archive PDF/A-2](workflows/pdfa_2.mdx)**, but with support for non-PDF/A attachments.
- Workflow **[Invoice](workflows/invoice.mdx)** for creating PDF/A-3 conformant invoices with attachments.
- Signature types *Windows - PAdES-B-B* and *PKCS#11 - PAdES-B-B* to create basic signatures that require no TSA nor revocation information.
### 2.4.0
17 February 2021
#### Added
- Tab **[Integration](integrate/README.mdx)** for configuring connections to allow easy integration of the Conversion Service into existing systems.
- New service **Conversion Service Connections** that allows combining input sources with output for easy integration into existing systems.
#### Changed
- Removed service **Conversion Service Folders** (superseded by the new service **Conversion Service Connections**).
- The value of property `type` of problem details object (RFC 7807) was changed to `http://www.pdf-tools.com/service/rest/errors/‹type›`.
#### Fixed
- Improved OCR recognition task scheduling: Each page is now processed in a separate task, which significantly reduces the amount of time a worker is blocked by OCR tasks and thus improves the latency of other high priority tasks.
- Improved OCR engine configuration: Specific configuration for each engine type.
### 2.3.0
29 January 2021
#### Added
- The REST interface now supports Cross-Origin Requests (CORS). By default, requests from all origins are allowed.
- **Archive PDF/A-2 workflow**: Profile option *Flatten annotations* in section **Document Optimization**.
### 2.2.0
16 December 2020
#### Added
- Docker image `pdftoolsag/conversion-service`.
- Changed license key format to `4H-VX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX`. License keys with the format `1-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX` are no longer supported.
- Conversion of RTF documents.
### 2.1.0
#### Changed
- A parallel installation of the 3-Heights® Document Converter is no longer required and no longer supported for this purpose.
### 2.0.0
#### Added
- Profile setting *Task timeout* for all workflows, to avoid the situation where a single long-running processing step can lead to timeouts in other unrelated jobs.
#### Fixed
- Improved email conversion: Attachments of emails where parts of the attachment are removed during the conversion process (e.g. a not convertible part of a ZIP file) are now listed as *Partially removed* inside the email header.
- Improved and harmonized messages of warnings and events.
- Improved conversion of Word, Excel, and PowerPoint: These types of documents are now converted directly within the Conversion Service through Microsoft Office applications.
## Version 1
This section describes all changes included in version 1 of the Conversion Service.
#### Added
- New requirement of Microsoft Windows Desktop Runtime 3.1 (Windows, x64) and Microsoft ASP.NET Core Runtime 3.1 (Windows, x64). This is in addition to the .NET Framework 4.7.
- View in the 4-Heights® Conversion Service Configurator GUI for submitting a support request.
- Profile option for job priority in Archive PDF/A-2 workflow.
- Profile configuration (Digital Signature) available in the Configurator GUI.
- Attachment information is shown as part of the email header.
- Possibility to import/export profile configurations.
- License-dependent view in the Conversion Service Configurator GUI for installing plugins.
- Document content overflow into the margin when converting emails is signaled with `ContentOverflowWarning`.
- Documentation panel in the Conversion Service Configurator GUI.
- Codes in the service status response of the REST interface.
- Service setting for proxy configuration.
- GUI Client for manual processing.
#### Changed
- Changed minimum required version of 3-Heights® Document Converter Enterprise Edition to version 6.5.
- Changed port to connect to 3-Heights® Document Converter Enterprise Edition to 7983.
- **REST interface**:
- Changed to return RFC 7807 Problem object instead of proprietary error object.
- Changed JSON serialization of `enum` values from integer to string.
- Changed XML objects to use no namespace in accordance `withopenapi.yaml`.
---
## Update Conversion Service
import DocCardList from '@theme/DocCardList';
Learn how to update the Conversion Service to the latest version in Windows Server or Docker.
PDF/A workflow steps
1. Analyze file type
In a first step, the documents are analyzed. If the file type of any document is unsupported, conversion is aborted. Otherwise, they are sent to the next processing step depending on their file type.
2. Validate & repair PDF (Quality Assurance)
To ensure document quality, PDF and PDF/A documents are validated. If a corruption is detected, the Conversion Service attempts to repair it.
3. Convert to PDF
Non-PDF documents (e.g images, Office documents, etc.) are converted to PDF if their format is supported by the Conversion Service.
Note: The conversion of Office documents requires an additional step which can only be enabled with an appropriate license.
4. Perform OCR
To make the resulting document searchable, OCR is performed on documents that require it. The recognized text is stored directly in the PDF.
Note: This is an optional step and can only be enabled with an appropriate license.
5. Apply stamping
Stamps such as barcodes, text stamps, image stamps or placeholders are added.
6. Convert to PDF/A
PDF documents that are not already PDF/A conforming are converted to a high-quality PDF/A.
Important: The actions performed in this step vary for PDF/A-1 and PDF/A-2 and PDF/A-3.
7. Merge / Collect
The converted documents of a job are merged or collected into a single document, depending on the profile setting.
8. Optimize
The resulting document is compressed and optimized for archiving. This includes several steps: redundant and unnecessary data for archiving is removed, images are compressed intelligently and fonts are merged and subset.
Note: This is an optional step and can only be enabled with an appropriate license.
8. Sign
The resulting document is digitally signed using the signature settings in the selected profile.
Note: this is an optional step and can only be enabled with an appropriate license.
## Accessibility
The **[Accessibility workflow](accessibility.mdx)** is designed to validate PDF documents for compliance with accessibility standards, including **PDF/UA (ISO 14289)**, **Web Content Accessibility Guidelines 2.1 (WCAG)**, and general **quality guidelines**.
## Dossier
The **[Dossier workflow](dossier.mdx)** is specifically designed to compile multiple PDF documents into a single dossier. All PDF document supplied to the job are merged into a single PDF in the order that they were added to the job.
## Invoice
The **[Invoice workflow](invoice.mdx)** is engineered specifically for preparing invoices. This workflow converts a main document to PDF/A-3 and attaches one or more files to the result. For example, to a PDF invoice an Excel table containing additional data can be attached.
## Archive TIFF
The **[Archive TIFF](tiff.mdx)** workflow is engineered specifically to prepare documents for archiving in suitable TIFF format.
## Sign
The **[Sign](sign.mdx)** workflow is engineered specifically for signing archived documents without removing the existing signatures.
## Enabling workflows
You can enable or disable the workflows available in the Conversion Service Configurator, in the **Workflows & Profiles** tab by clicking the toggle button right next to the workflow name. Your changes are kept in memory until you click **Save & Restart Service**.
---
## Accessibility workflow
This workflow is designed to validate PDF documents for compliance with accessibility standards, including **PDF/UA (ISO 14289)**, **Web Content Accessibility Guidelines 2.1 (WCAG)**, and general **quality guidelines**. The output includes a structured report containing accessibility issues categorized by severity and standard.
This workflow supports the following features:
- PDF/UA validation (ISO 14289-1).
- WCAG 2.1 validation (PDF-specific interpretations).
- General quality checks.
- Customizable filtering of issue severities (for example, ignore or deny warnings).
- JSON and XML report outputs.
- Warning mappings with extensibility based on the [PAC tool](https://pac.pdf-accessibility.org/en).
- Compatible with Docker and Windows deployments.
## Supported input file formats
This workflow supports any input in **PDF format**:
- PDF 1.x, PDF 2.0
- PDF/A-1, PDF/A-2, PDF/A-3
- PDF with tags, annotations, or layers.
## Output structure
The result is structured as a hierarchy of **issue nodes**, each of which may contain:
- Severity: `Warning`, `Failure`, `Termination`
- Standard: `PDF/UA`, `WCAG`, `Quality`
- Category and Subcategory (for example *Basic Requirements → Natural Language*)
- The bounding box (for visual issues)
- Page index
- Message
## Output formats
- **JSON**
- **XML**
### Document options
Document options apply only to a specific input. It allows you to determine specific properties based on an individual document rather than as a global setting (either determined by the job or the profile). Any subsequent jobs processed with the workflow profile use the profile's default settings.
| Type | Option | Required | Description |
|----------------------|--------------------|-----------|-------------|
| Document property | `DOC.PASSWORD` | **Optional** | Sets the password for the document. |
---
## Conversion workflow
This workflow is engineered specifically for converting documents to PDF 1.x.
Unlike the Archive PDF/A workflows, files are only converted to PDF (and not PDF/A), the file format is not validated and the output documents cannot be signed.
The Conversion workflow supports the following features:
- Compression and optimization for speed or size
- Optical character recognition (OCR)
- Office file conversion (as required)
- Configuration of attachment conversion
## Supported file formats for Conversion workflow
The Conversion workflow supports the following file formats:
| Content type | File type |
|------------------|--------------------------------------------------------------------------------------|
| Document formats | PDF 1.x, PDF 2.0, PDF/A-1, PDF/A-2, PDF/A-3 |
| Image formats | JPEG, JPEG200, TIFF, BMP, GIF, JBIG2, PNG, HEIC, HEIF, WebP, JFIF |
| Email | EML, MSG (without encryption) |
| Word | DOC, DOT, DOCX, DOCM, DOTX, DOTM, RTF, XML (WordprocessingML 2003) |
| Excel | XLS, XLT, XLSX, XLSM, XLTX, XLTM, XML (SpreadsheetML 2003) |
| PowerPoint | PPT, PPS, PPTX, PPTM, PPSX, PPSM |
| OpenOffice | ODT, ODS, ODP |
| Other | CSV, HTML, HTM (prepared for archiving), TXT, XML, ZIP (without password protection) |
## Configure the workflow
The workflow's profile provides detailed configuration options for file conversion processes. All processing steps can be enabled and customized within the [profile configuration](../configure/configure-profiles.mdx). The Conversion workflow includes the following configurable features:
- [Optimize for speed or size](#optimize-for-speed-or-size)
- [Convert mode for child documents (attachments)](#convert-mode-for-child-documents-attachments)
- [Collect mode](#collect-mode)
### Optimize for speed or size
You can select whether to optimize files for:
- **Speed**: Processing time
- **Size**: Minimal document file size
### Convert mode for child documents (attachments)
Certain child documents, such as attachments to emails or PDF documents, can be skipped (removed) during conversion to PDF.
The convert mode can be specified based on the type of the child document, its filename, or the type of its parent document.
For example, by default executables attached to an email are removed.
If desired, rules can be added to attach files that can not be converted (for example PDF documents containing unrendered XFA, HTML documents) in their original source format to the resulting output document.
### Collect mode
The collect mode configuration defines how a converted document and its child documents are combined.
The collect mode can be configured for each document type and also defines how errors are handled.
For example, emails can be converted by creating a PDF collection (portfolio) of their bodies and attachments.
When converting Word documents, all embedded files can be merged into the converted PDF.
### Linearization
Linearization internally restructures document content for faster loading and rendering in web browsers. However, linearization has trade-offs such as increased file size and a limited effect on rendering performance. Use PDF linearization when you need to load the first page of a PDF fast on the web.
The Conversion Service doesn't support linearization of attached documents (child documents).
:::info
Although linearization provides fast, page-by-page loading over a network connection, it is not recommended for all use cases as it can considerably increase file size and has a limited effect.
:::
## Job and document options for the Conversion workflow
The Conversion workflow lets you use [job and document options](../configure/configure-job-and-document-options.mdx) to pass job and document-specific values to be used when processing documents using the workflow.
:::note
Job and document options you pass at runtime affect only the current job. When you change a setting of the job or document options, that change applies only to the current job. For the next job, the workflow reverts to the profile settings (saved default) unless you pass job or document options again.
:::
### Job options
Job options apply to all documents processed in the same job. Any subsequent jobs processed with the workflow profile use the profile's default settings.
| Type | Option | Description |
| --- | ---- | --- |
| OCR | `OCR` | Turn on and off optical character recognition for the job. All settings must be previously set up in the profile. If `true`, documents included in the job are processed to recognize any images as text (as appropriate). If `false`, no OCR is performed. |
| **[Metadata](metadata.mdx)** | `META.AUTHOR` | The author of the document |
| **[Metadata](metadata.mdx)** | `META.TITLE` | The title of the document |
| **[Metadata](metadata.mdx)** | `META.SUBJECT` | The subject of the document |
| **[Metadata](metadata.mdx)** | `META.KEYWORDS` | Keywords that apply to the document |
| Document settings | `PDF.LINEARIZE` | Enable or disable linearization of the output PDF. |
:::note
You can also set [extended metadata properties](metadata.mdx#extended-properties) apart from the standard metadata properties.
:::
### Document options
Document options apply only to a specific input. It allows you to determine specific properties based on an individual document, rather than as a global setting (either determined by the job or the profile). Any subsequent jobs processed with the workflow profile use the profile's default settings.
| Type | Option | Description |
| --- | ---- | --- |
| Document property | `DOC.PASSWORD` | Set the password for the document. |
---
## Dossier workflow
import useBaseUrl from '@docusaurus/useBaseUrl';
Learn how to merge multiple PDFs into a single file using the dossier workflow. This process is designed to combine several PDF documents into one cohesive dossier. The PDFs are merged in the order that users provide them.
Key features of the dossier workflow include:
- Fully customizable title page, including its title, subtitle, and background.
- Extensively customizable table of contents.
- Bookmarks to add navigation and structure to the dossier.
- Stamping options such as watermarks, headers, or footers.
- Optional: Conversion to PDF/A.
## What is a dossier?
A PDF **dossier** is a structured compilation of multiple documents merged into a single PDF file. The dossier often includes a table of contents, outline (document bookmarks), and metadata for easy navigation and organization. It is frequently used in business, legal, academic, and government contexts to present information in a clear, professional, and accessible format.
## Supported file formats for dossier workflow
This workflow takes PDF files as input. To use other document formats, convert them to PDF using a **preprocessing** step in the dossier workflow, which points to another workflow that performs the preprocessing conversion.
## Add a title page
You can configure this workflow to create a title page for the dossier. The title page contains the dossier's title and subtitle.
The font, size, placement, and alignment of the text are fully configurable.
Additionally, you can configure a PDF document to be used as a custom background for the title page. You can customize the title page for each job using the [`DOSSIER-TITLE`](#job-options) and [`DOSSIER-SUBTITLE`](#job-options) job options.
## Structure the dossier
If the title from the metadata is not suitable, it can be overridden by using the [`DOCUMENT-TITLE`](#job-options) option.
To organize the dossier effectively, you can create a [Table of Contents](#create-the-table-of-contents) and a [document outline](#create-the-document-outline) (bookmarks). By default, each document's title is derived from its metadata.
If the metadata title is not suitable, you can override it using the [`DOCUMENT-TITLE`](#job-options) option.
### Create the table of contents
The **table of contents (TOC)** provides an overview of the dossier's structure, making it easier to navigate.
By default, the TOC follows the existing outline structure tree of the input documents and supports multiple configurable nesting levels. Optionally, you can create a parent entry for each input document.
Customization options include:
- **For the entire job**: Use the [`TOC-TITLE`](#job-options) option to define a custom title for the table of contents.
- **For individual input documents**: Use the [`ADD-DOCUMENT-TOC-ITEM`](#document-options) option to include a document in the TOC and [`DOCUMENT-TOC-TITLE`](#document-options) to set its title.
### Create the document outline
The **document outline** (also known as **bookmarks**) allows users to quickly navigate to specific sections of the dossier.
By default, the dossier workflow uses the outline structure of the input documents. Additionally, a parent bookmark can be generated for each document if needed.
Customization options include:
- **For the entire job**: Use the [`TOC-OUTLINE-TITLE`](#job-options) option to set a custom title for the document outline.
- **For individual input documents**: Use the [`ADD-DOCUMENT-OUTLINE`](#document-options) option to include a document in the outline and [`DOCUMENT-OUTLINE-TITLE`](#document-options) to set its title.
## Add stamps
Review a general overview of stamping in [Stamp and annotation](stamping.mdx) documentation. You can further customize stamps for the dossier workflow using the `DOCUMENT-STAMP-TITLE` option or using a custom option `CUSTOM.OPTION_NAME`. For more information about this customization, review [Placeholders](../configure/configure-stamping.mdx#placeholders) section in stamping documentation.
## Example of the dossier workflow
This example uses the [shell client](../integrate/shell-client.mdx) to create a dossier from a cover page and two chapters. For the second chapter, the name of the bookmark is explicitly overridden.
```
C:\Temp>pdfclient -v -w Dossier -do ADD-DOCUMENT-OUTLINE false ^
chapter-1.pdf -do DOCUMENT-OUTLINE-TITLE "Chapter 2: XYZ" chapter-2.pdf out.pdf
Creating job (id job1_5g5fkycbhhe)
Adding file ".\chapter-1.pdf" (id jgvmhpyquh0)
Adding file ".\chapter-2.pdf" (id 4ogify1xd31)
Output: "out.pdf"
- Info: Assembled PDF files 'chapter-1.pdf' and 'chapter-2.pdf' into dossier 'out.pdf'.
```
## Job and document options for the Dossier workflow
The Dossier workflow lets you use [job and document options](../configure/configure-job-and-document-options.mdx) to pass job and document-specific values to be used when processing documents using the workflow.
:::note
Job and document options you pass at runtime affect only the current job. When you change a setting of the job or document options, that change applies only to the current job. For the next job, the workflow reverts to the profile settings (saved default) unless you pass job or document options again.
:::
### Job options
Job options apply to all documents processed in the same job. For any subsequent jobs processed with the workflow profile, use the profile's default settings.
| Type | Option | Description |
| --- | ---- | --- |
| **[Title page](#add-a-title-page)** | `DOSSIER-TITLE` | Adds a title page with a title for the dossier. This option overrides the value specified in the profile configuration. The option should only be set at the job level and is ignored at the document level. |
| **[Title page](#add-a-title-page)** | `DOSSIER-SUBTITLE` | Adds a title page with a subtitle for the dossier. This option overrides the value specified in the profile configuration. The option should only be set at the job level and is ignored at the document level. |
| **[Table of contents](#create-the-table-of-contents)** | `TOC-TITLE` | Sets the heading for the table of contents. This option overrides the value specified in the profile configuration. The option should only be set at the job level and is ignored at the document level. |
| **[Table of contents](#create-the-table-of-contents)** | `ADD-DOCUMENT-TOC-ITEM` | Creates a table of contents entry for each document included in the job. It can also be set at document level. `true` (default): entry in the table of contents is added for the input document. Existing bookmarks of the input document are added as sub-entries. `false`: The existing bookmarks of the input document are added directly to the top level of the table of contents. This can be useful in the following use cases: Special input documents that don't represent a chapter in the output document, such as a cover sheet or table of contents.Documents that already contain all necessary bookmarks. |
| **[Document outline](#create-the-document-outline)** | `ADD-DOCUMENT-OUTLINE` | Adds an outline (bookmark) for all documents in the job. `true` (default): A new bookmark is added to the document outline for the input document. Existing bookmarks of the input document are preserved and added as children to the newly created bookmark.`false`: The existing bookmarks of the input document are added directly to the top level of the document outline. This can be useful in the following use cases:Special input documents that don't represent a chapter in the output document, such as a cover sheet or table of contents.Documents that already contain all necessary bookmarks. |
|**[Document outline](#create-the-document-outline)** | `TOC-OUTLINE-TITLE` | Sets the title for the outline. The name of the bookmark created for the table of contents (if enabled). If it is omitted, one of the following values is used instead (in order of precedence): The value of the `TOC-TITLE` option.The title of the table of contents is configured in the profile. `TOC-OUTLINE-TITLE` should only be set at the job level and cannot be configured in the profile configuration. |
| **[Metadata](metadata.mdx)** | `META.AUTHOR` | The author of the document |
| **[Metadata](metadata.mdx)** | `META.TITLE` | The title of the document |
| **[Metadata](metadata.mdx)** | `META.SUBJECT` | The subject of the document |
| **[Metadata](metadata.mdx)** | `META.KEYWORDS` | Keywords that apply to the document |
:::note
You can also set [extended metadata properties](metadata.mdx#extended-properties) apart from the standard metadata properties.
:::
### Document options
Document options apply only to a specific input. It allows you to determine specific properties based on an individual document rather than as a global setting (either determined by the job or the profile). For any subsequent jobs processed with the workflow profile, use the profile's default settings.
| Type | Option | Description |
| ----- | ------- | --- |
| **[Document property](#structure-the-dossier)** | `DOCUMENT-TITLE` | Sets the title for the document by overriding the title determined by the [metadata](metadata.mdx). If no title is set in the metadata, `DOCUMENT-TITLE` is used for the table of contents, document outline, and stamp placeholder. It can be overridden by the `DOCUMENT-OUTLINE-TITLE`, `DOCUMENT-TOC-TITLE`, and `DOCUMENT-STAMP-TITLE` options. If it is omitted and no other specific option is set, one of the following values is used instead (in order of precedence):The document title from the document metadata.The filename of the input document (without the extension). This option should only be set at the document level and cannot be configured in the profile configuration. |
| Document property | `DOC.PASSWORD` | Set the password for the document. |
| **[Document outline](#create-the-document-outline)** | `ADD-DOCUMENT-OUTLINE` | Adds an outline (bookmark) for the specified document only, rather than all documents in the job. `true` (default): A new bookmark is added to the document outline for the input document. Existing bookmarks of the input document are preserved and added as children to the newly created bookmark.`false`: The existing bookmarks of the input document are added directly to the top level of the document outline. This can be useful in the following use cases:Special input documents that don't represent a chapter in the output document, such as a cover sheet or table of contents.Documents that already contain all necessary bookmarks. |
| **[Document outline](#create-the-document-outline)** |`DOCUMENT-OUTLINE-TITLE` | Sets the name of the bookmark in the dossier outline. If this option is omitted, one of the following values is used instead (in order of precedence):The value of the `DOCUMENT-TITLE` option.The document title from the document metadata.The filename of the input document (without the extension). This option should only be set at the document level and cannot be configured in the profile configuration. |
| **[Table of contents](#create-the-table-of-contents)** | `ADD-DOCUMENT-TOC-ITEM` | Adds an entry in the table of contents for the specified document only, rather than all documents in the job. It can also be set at job level. `true` (default): entry in the table of contents is added for the input document. Existing bookmarks of the input document are added as sub-entries. `false`: The existing bookmarks of the input document are added directly to the top level of the table of contents. This can be useful in the following use cases: Special input documents that don't represent a chapter in the output document, such as a cover sheet or table of contents.Documents that already contain all necessary bookmarks. |
| **[Table of contents](#create-the-table-of-contents)** | `DOCUMENT-TOC-TITLE` | Sets the name of the entry in the table of contents for the specified document. If this option is omitted, one of the following values is used instead (in order of precedence):The value of the option `DOCUMENT-TITLE`.The document title from the document metadata.The filename of the input document (without the extension).This option should only be set at the document level and cannot be configured in the profile configuration. |
| **[Stamp options](#add-stamps)**| `DOCUMENT-STAMP-TITLE` | Sets the title of the document used for stamping, for example, for the `[input:DOCUMENT.TITLE]` placeholder (if used). If this option is omitted, one of the following values is used as placeholder value instead (in order of precedence): The value of the option `DOCUMENT-TITLE`.The document title from the document metadata.The filename of the input document (without the extension).This option should only be set at the document level and cannot be configured in the profile configuration. Accepts [placeholders](../configure/configure-stamping.mdx#placeholders). |
| **[Stamp options](#add-stamps)** | `CUSTOM.OPTION_NAME` | Options whose name starts with **`CUSTOM.`** define custom placeholder variables that can be used with the placeholder format. See [Placeholders](../configure/configure-stamping.mdx#placeholders). |
---
## Invoice workflow
This workflow is engineered specifically for preparing invoices. This workflow converts a main document to PDF/A-3 and attaches one or more files to the result. For example, you can attach an Excel table containing additional data to a PDF invoice.
The workflow supports the following features:
- Conversion to PDF/A-3 format
- Additional document attachments
- Office conversion (optional)
- Digital signatures (optional)
## Supported file formats for Invoice workflow
This workflow supports PDF and MS Word as input formats.
:::note
If you want support for formats such as ZUGFeRD, let us know through the [Contact page](https://www.pdf-tools.com/contact/).
:::
## Convert to PDF/A-3
This workflow has been optimized for the conversion of transactional documents. It supports conversion of Word and PDF documents to PDF/A-3.
## Attach documents
To attach additional documents to a main document, all documents must be added to a single job.
The documents to attach and additional properties can be set using the [`DOC.ROLE`](#document-options), [`AF.RELATIONSHIP`](#document-options), [`AF.MODDATE`](#document-options), and [`AF.DESCRIPTION`](#document-options) document options. These values are written into the result document and are visible to a user in the list of attached documents.
## Example of the workflow
This example uses the [shell client](../integrate/shell-client.mdx) to attach `supplement.xls` to the main document `invoice.docx`.
Note that the `-do ‹name› ‹value›` option applies a document option to the subsequent input file.
```
C:\Temp> pdfclient -v -w Invoice invoice.docx ^
-do DOC.ROLE attached -do AF.RELATIONSHIP Supplement supplement.xls ^
out.pdf
Creating job (id job123_4q5mprmmrz0)
Adding file "invoice.docx" (id 0kk1ddv0uzg)
Adding file "supplement.xls" (id 2fg4ufg3qmz)
Output: "invoice.pdf"
- Info: Converted Word document 'invoice.docx' to PDF.
- Info: Converted 'invoice.pdf' to PDF/A-3u.
- Info: Attached file 'supplement.xls' to 'invoice.pdf'.
```
## Job and document options for the Invoice workflow
The Invoice workflow lets you use [job and document options](../configure/configure-job-and-document-options.mdx) to pass job and document-specific values to be used when processing documents using the workflow.
:::note
Job and document options you pass at runtime affect only the current job. When you change a setting of the job or document options, that change applies only to the current job. For the next job, the workflow reverts to the profile settings (saved default) unless you pass job or document options again.
:::
### Job options
Job options apply to all documents processed in the same job. Any subsequent jobs processed with the workflow profile use the profile's default settings.
Type | Option | Description |
| --- | ---- | --- |
| **[Metadata](metadata.mdx)** | `META.AUTHOR` | The author of the document |
| **[Metadata](metadata.mdx)** | `META.TITLE` | The title of the document |
| **[Metadata](metadata.mdx)** | `META.SUBJECT` | The subject of the document |
| **[Metadata](metadata.mdx)** | `META.KEYWORDS` | Keywords that apply to the document |
:::note
You can also set [extended metadata properties](metadata.mdx#extended-properties) apart from the standard metadata properties.
:::
### Document options
Document options apply only to a specific input. It allows you to determine specific properties based on an individual document, rather than as a global setting (either determined by the job or the profile). Any subsequent jobs processed with the workflow profile use the profile's default settings.
| Type | Option | Required | Description |
|----------------------|--------------------|-----------|-------------|
| [Attach documents](#attach-documents) | `DOC.ROLE` | **Required** | Defines the document's role. Supported values are: `main` (default): The main document. Each job must have one main document.`attached`: A document attached to the main document. Multiple attached documents may exist in a job. |
| [Attach documents](#attach-documents) | `AF.RELATIONSHIP` | **Optional** | Defines the relationship of the attached document to the main document. Supported values are: `Unspecified` (default): Used when the relationship is unknown or cannot be described using the other values.`Source`: The attached document is the original source material for the main document.`Data`: The attached document represents information used to derive a visual presentation (for example table or graph).`Alternative`: The attached document is an alternative representation of content, such as audio.`Supplement`: The attached document provides a supplemental version of the original source or data that is more easily consumable (for example a MathML version of an equation). |
| [Attach documents](#attach-documents) | `AF.MODDATE` | **Optional** | Defines the date and time when the attached document was last modified. For example: `"2009-05-19T09:15:22.0000000+02:00"` |
| [Attach documents](#attach-documents) | `AF.DESCRIPTION` | **Optional** | Descriptive text associated with the attached document. |
| Document property | `DOC.PASSWORD` | **Optional** | Sets the password for the document. |
---
## Metadata in workflows
import PenIcon from '/img/pen-solid.svg';
Learn how to customize the metadata of the converted PDFs. This feature is available in all workflows.
:::note
Metadata are applied only to the main result document and not to embedded files or any other contained documents.
Set all runtime options for further customizing the metadata at the job level, not at the document level.
:::
## Standard properties
The four standard PDF metadata properties that can be customized are **Author**, **Title**, **Subject**, and **Keywords**.
You can configure a fixed value in the profile configuration for each of these mentioned properties. If no value is configured, the original value is preserved (if available).
You can also provide the values dynamically using the following job options:
| Option | Description |
|---|---|
| `META.AUTHOR` | The author of the document. |
| `META.TITLE` | The title of the document. |
| `META.SUBJECT` | The subject of the document. |
| `META.KEYWORDS` | Keywords that apply to the document. |
## Extended properties
Extended metadata is defined by the XMP standard, with properties grouped into schemas.
The Conversion Service allows setting XMP property values from the follwoing schemas:
- **Dublin Core schema**
- **XMP Basic schema**
- **XMP Rights Management**
- Your custom extension schema
:::tip
You can find all the specific schemas and their respective properties in the Conversion Service Configurator:
1. Open the Conversion Service Configurator, and then click **Workflow & Profiles**.
1. Select a profile where you would like to configure the properties. and then click the CUSTOM.OPTION_NAME
No default value provided: [custom:OPTION_NAME] this makes the job and document option required. If the job and document option is not provided during processing, an error is raised.
[custom:REVIEWER]
Default value provided: [custom:OPTION_NAME, 'DEFAULT_VALUE'] this makes the job and document option optional. If the corresponding job and document option is not provided during processing, the specified default value will be used. The single quotes (`'`) around the default value are a required in this syntax.
[custom:REVIEWER, 'John Doe']
Empty default value provided: [custom:OPTION_NAME, ''] this makes the job and document option optional. If the corresponding job option is not provided during processing, no value will be set (the field will be left empty). Include empty single quotes as the default value (`''`). The single quotes (`'`) are required in this syntax.
[custom:REVIEWER, '']
## Advanced usage
For advanced users, you can further customize and refine the metadata using the following job option:
| Option | Description |
|---|---|
| `META.XMP` | A complete XMP packet replacing the metadata of the input document.This option can set all kinds of metadata, including [standard properties](#standard-properties), [extended properties](#extended-properties), and [custom extension schemas](#custom-extension-schemas).Any properties set using standard mechanisms take precedence over values provided in this XMP packet. |
:::note
When creating a PDF/A document, the XMP metadata must include a complete schema definition for all custom extension schemas. This definition can be provided:
- Directly in the XMP packet.
- Using [custom extension schema](#custom-extension-schemas) configuration, with the **Force Definition** setting enabled.
:::
---
## Archive PDF/A-1 workflow
This workflow is engineered specifically for preparing documents for archiving, specifically where PDF/A-2 or PDF/A-3 conformance is not allowed.
This workflow is disabled by default because it is recommended you use [Archive PDF/A 2](pdfa_2.mdx) workflow for archiving. Since PDF/A-2 is based on a newer version of the PDF standard, more PDF features are allowed such as transparency, layers, embedded files, and a less restrictive internal file structure.
For these reasons, achieve fewer conversion errors and better conversion quality with the Archive PDF/A-2 workflow. Particularly, if you use the Conversion Service in a Docker container where document content rasterization is unavailable, use PDF/A-2 workflow instead to avoid visual differences, removed transparency, or other potential issues.
:::info
More information on PDF/A-2, read [PDF/A-2 overview](https://www.pdf-tools.com/pdf-knowledge/all-about-pdf-a-long-term-archiving/).
:::
{/* Clarify this section with the full list of features available for the Archive PDF/A-1 workflow
The Archive PDF/A-1 workflow supports these features:
- Conversion to PDF/A-1 format
*/}
## Supported file formats for Archive PDF/A-1 workflow
The Archive PDF/A-1 workflow supports the following file formats:
| Content type | File type |
|------------------|--------------------------------------------------------------------------------------|
| Document formats | PDF 1.x, PDF 2.0, PDF/A-1, PDF/A-2, PDF/A-3 |
| Image formats | JPEG, JPEG200, TIFF, BMP, GIF, JBIG2, PNG, HEIC, HEIF, WebP, JFIF |
| Email | EML, MSG (without encryption) |
| Word | DOC, DOT, DOCX, DOCM, DOTX, DOTM, RTF, XML (WordprocessingML 2003) |
| Excel | XLS, XLT, XLSX, XLSM, XLTX, XLTM, XML (SpreadsheetML 2003) |
| PowerPoint | PPT, PPS, PPTX, PPTM, PPSX, PPSM |
| OpenOffice | ODT, ODS, ODP |
| Other | CSV, HTML, HTM (prepared for archiving), TXT, XML, ZIP (without password protection) |
:::caution Note on OpenOffice formats
PDF conversion of OpenDocument Format depends on the rendering in Microsoft Word, Excel or PowerPoint.
In particular, visual differences may occur with tables and tabs.
The visual differences caused by the rendering of shapes are usually not acceptable.
:::
:::caution Note on HTML format
HTML documents need to be self-contained (layout information and images are either inline or available on the web) and suited for portrait page layout.
JavaScript content is disabled during processing.
:::
:::caution Note on XML format
Layout information and images need to be available on the web.
:::
The conversion of most file formats is enabled by default in the profile's Convert mode for child documents (attachments).
## Features and limitations
Compared to the PDF/A-2 workflow, this workflow has the following features and limitations:
### Collect mode
The PDF/A-1 standard does not allow embedded files. Therefore, the only collect mode configuration available is **Merge**.
### Document content rasterization
Certain graphical features of PDF documents are not allowed in PDF/A-1; for example, transparency. The removal of such features can lead to severe visual differences that may render the page's content unreadable.
The Windows version of the product can preserve the visual appearance of such documents by converting the pages' content to images (content rasterization).When doing so, a *content rasterized* warning is generated. If possible, content rasterization preserves the pages' extractable text, links, outlines and viewer preferences.
The Docker version cannot rasterize pages. Therefore, the conversion of such files leads to *transparency removed* or *visual differences* warning depending on whether the visual differences are caused by the removal of transparency.
### PDF/A-1 specific conversion warnings
The following warnings occur more frequently when converting to PDF/A-1:
- Annotation removed
- Content rasterized
- Layers removed
- Transparency removed
- Visual differences
The workflow profile's conversion settings for the mentioned warnings is particularly important.
Note: Content rasterized warning appears only in Windows where content rasterization is available; Transparency removed warning only appears in Docker images, where content rasterization isn't available.
### Sign
Document signing is currently not implemented.
### Linearization
Linearization internally restructures document content for faster loading and rendering in web browsers. However, linearization has trade-offs such as increased file size and a limited effect on rendering performance. Use PDF linearization when you need to load the first page of a PDF fast on the web.
The Conversion Service doesn't support linearization of attached documents (child documents).
:::info
Although linearization provides fast, page-by-page loading over a network connection, it is not recommended for all use cases as it can considerably increase file size and has a limited effect.
:::
## Job and document options for the PDF/A-1 workflow
The PDF/A-1 workflow lets you use [job and document options](../configure/configure-job-and-document-options.mdx) to pass job and document-specific values to be used when processing documents using the workflow.
:::note
Job and document options you pass at runtime affect only the current job. When you change a setting of the job or document options, that change applies only to the current job. For the next job, the workflow reverts to the profile settings (saved default) unless you pass job or document options again.
:::
### Job options
Job options apply to all documents processed in the same job. Any subsequent jobs processed with the workflow profile use the profile's default settings.
Type | Option | Description |
| --- | ---- | --- |
| Document compression and optimization | `OPTIMIZE` | Turn on or off document compression and optimization. All settings must be previously set up in the profile. If `true`, documents included in the job are compressed and optimized according to the optimization profile set in the profile settings. If `false`, no compression and optimization is performed. Documents can be optimized according to five profiles:**Web**: Compresses the file without affecting viewing quality on digital devices**Print**: Compresses the file without affecting print quality**Max**: Removes redundant data and reduces image resolution to achieve a minimal viable file size**MRC**: Profile designed to process mixed raster content**Archive**: Prepares a document for archiving in PDF/A format |
| OCR | `OCR` | Turn on and off optical character recognition for the job. All settings must be previously set up in the profile. If `true`, documents included in the job are processed to recognize any images as text (as appropriate). If `false`, no OCR is performed. |
| [Metadata](metadata.mdx) | `META.AUTHOR` | The author of the document |
| [Metadata](metadata.mdx) | `META.TITLE` | The title of the document |
| [Metadata](metadata.mdx) | `META.SUBJECT` | The subject of the document |
| [Metadata](metadata.mdx) | `META.KEYWORDS` | Keywords that apply to the document |
| Document settings | `PDF.LINEARIZE` | Enable or disable linearization of the output PDF. |
:::note
You can also set [extended metadata properties](metadata.mdx#extended-properties) apart from the standard metadata properties.
:::
### Document options
Document options apply only to a specific input. It allows you to determine specific properties based on an individual document, rather than as a global setting (either determined by the job or the profile). Any subsequent jobs processed with the workflow profile use the profile's default settings.
| Type | Option | Description |
| --- | ---- | --- |
| Document property | `DOC.PASSWORD` | Set the password for the document. |
---
## Archive PDF/A-2 workflow
The Archive PDF/A-2 workflow is engineered to prepare documents for archiving.
In particular, you can:
- Maintain the original appearance and structure of the document.
- Minimize the loss of information.
- Ensure traceability and reproducibility of the changes made to the document.
The Archive PDF/A-2 workflow supports the following features:
- Conversion to PDF/A-2 format (PDF/A-2b, PDF/A-2u, and PDF/A-2a)
- Optimization of PDF/A structure (optional)
- Office conversion (optional)
- Optical character recognition (optional)
- Digital signatures (optional)
:::info Conformance levels
The Conversion Service supports Basic (PDF/A-2b), Unicode (PDF/A-2u), and accessibility (PDF/A-2a) conformance levels.
All conformance levels are incremental; the subsequent conformance level includes the requirements of the previous level and other additional requirements.
For example, all level U (Unicode) PDF/A-2 documents are **valid level B (Basic) documents**.
The Archive PDF/A-2 workflow automatically tries to convert the input document to the **highest conformance level** for PDF/A-2 (usually PDF/A-2a). If the input document is PDF/A-2b or a PDF without structure information, the workflow tries to convert it to PDF/A-2u. If the workflow cannot convert to the PDF/A-2u conformance level, it converts to PDF/A-2b or ends the conversion with a failure.
:::
## Supported file formats for Archive PDF/A-2
The Archive PDF/A-2 workflow supports the following file formats:
| Content type | File type |
|------------------|--------------------------------------------------------------------------------------|
| Document formats | PDF 1.x, PDF 2.0, PDF/A-1, PDF/A-2, PDF/A-3 |
| Image formats | JPEG, JPEG200, TIFF, BMP, GIF, JBIG2, PNG, HEIC, HEIF, WebP, JFIF |
| Email | EML, MSG (without encryption) |
| Word | DOC, DOT, DOCX, DOCM, DOTX, DOTM, RTF, XML (WordprocessingML 2003) |
| Excel | XLS, XLT, XLSX, XLSM, XLTX, XLTM, XML (SpreadsheetML 2003) |
| PowerPoint | PPT, PPS, PPTX, PPTM, PPSX, PPSM |
| OpenOffice | ODT, ODS, ODP |
| Other | CSV, HTML, HTM (prepared for archiving), TXT, XML, ZIP (without password protection) |
:::info Note on OpenOffice formats
PDF conversion of OpenDocument Format depends on the rendering in Microsoft Word, Excel, or PowerPoint. In particular, visual differences may occur with tables and tabs. Visual differences caused by the rendering of shapes are usually not acceptable.
:::
:::info Note on HTML format
HTML documents must be self-contained (layout information and images are either embedded within documents or available online) and suited for portrait page layout. JavaScript content is disabled during processing.
:::
:::info Note on XML format
Layout information and images must be available online.
:::
The conversion of most file formats is enabled by default in the Convert mode.
## Configure the workflow
The Archive PDF/A-2 workflow's profile provides detailed configuration options for converting files to the PDF/A-2 standard. The [profile configuration](../configure/configure-profiles.mdx) allows for the customization of all processing steps.
:::tip
To view the processing steps in the Archive PDF/A workflows, see [PDF/A workflow steps](./README.mdx#archive-pdfa-workflows).
:::
### Convert mode for child documents (attachments)
Define which documents the PDF/A-2 workflow converts (Convert option) and skips (removes) from the result using the **Convert mode for child documents (attachments)** configuration. When removing documents, the Conversion Service generates a warning (*Skip with Warning* option) or an informational message (*Skip* option).
Using the Convert mode for child documents (attachments), you can define rules based on the child document type, its filename, or the type of its parent document. Based on these parameters, you can configure the PDF/A-2 workflow to convert, keep, or skip(remove) various child documents. For example, by default, the PDF/A-2 workflow converts Microsoft Office files to PDF/A, removes executables, and removes other non-convertible documents with a warning.
### Collect mode
The collect mode defines how a converted document and its child documents are combined. The collect mode can be specified for each document type individually.
There are two collect mode categories:
- **Merge**: Merge the pages of multiple PDF files into a single document.
- **Attach**: Attach (embedded) child documents into a PDF file.
For example, you can configure the PDF/A-2 workflow to convert emails into a PDF collection (Portfolio) of their bodies and attachments. When converting Word documents, their embedded files can be attached to the converted PDF. A PDF collection (Portfolio) is a special case of the **Attach collect mode**, where the parent document contains no pages. Still, the resulting portfolio PDF displays a convenient table of the attached documents for easy navigation. The advantage of the Attach collect mode is that it can preserve all information of the input files and the files' structure.
The **Merge collect mode** creates simple files that can be processed and viewed by all PDF applications. The disadvantage is that this mode can only merge PDF files. Furthermore, not all information can be preserved when merging PDF files. For example, document metadata, signatures, and certain interactive form fields cannot be merged and must be removed. Also, logical structure (tagging) information might be less meaningful after merging.
The recommended collect mode configuration for the **Merge use case**:
| Doc type | Collect mode |
|---|---|
| Job | Merge |
| Word | Merge or Attach |
| Excel | Merge or Attach |
| PowerPoint | Merge or Attach |
| Email | Merge or Attach |
| Archive (ZIP) | Merge or Attach |
| PDF | Preserve Structure |
The recommended collect mode configuration for the **Attach use cases**:
| Doc type | Collect mode |
|---|---|
| Job | Collection or single document |
| Word | Attach |
| Excel | Attach |
| PowerPoint | Attach |
| Email | Attach |
| Archive (ZIP) | Collection or single document |
| PDF | Preserve Structure |
:::tip
If necessary, the Flatten collect mode can be used for PDF files to flatten the structure of PDF documents. Up to version 3.1 of the Conversion Service, this has been the default behavior.
:::
### Child error handling
This configuration defines how errors are handled during the conversion of child documents. In case of an error, the child document can either be skipped (removed) from the result and a warning generated (*Skip with Warning* option). Alternatively, the conversion of the parent document can be aborted with an error (*Strict* option).
### Linearization
Linearization internally restructures document content for faster loading and rendering in web browsers. However, linearization has trade-offs such as increased file size and a limited effect on rendering performance. Use PDF linearization when you need to load the first page of a PDF fast on the web.
The Conversion Service doesn't support linearization of attached documents (child documents).
:::info
Although linearization provides fast, page-by-page loading over a network connection, it is not recommended for all use cases as it can considerably increase file size and has a limited effect.
:::
## Job and document options for the PDF/A-2 workflow
The PDF/A-2 workflow lets you use [job and document options](../configure/configure-job-and-document-options.mdx) to pass job and document-specific values to be used when processing documents using the workflow.
:::note
Job and document options you pass at runtime affect only the current job. When you change a setting of the job or document options, that change applies only to the current job. For the next job, the workflow reverts to the profile settings (saved default) unless you pass job or document options again.
:::
### Job options
Job options apply to all documents processed in the same job. Any subsequent jobs processed with the workflow profile use the profile's default settings.
Type | Option | Description |
| --- | ---- | --- |
| Document compression and optimization | `OPTIMIZE` | Turn on or off document compression and optimization. All settings must be previously set up in the profile. If `true`, documents included in the job are compressed and optimized according to the optimization profile set in the profile settings. If `false`, no compression and optimization is performed. Documents can be optimized according to five profiles:**Web**: Compresses the file without affecting viewing quality on digital devices**Print**: Compresses the file without affecting print quality**Max**: Removes redundant data and reduces image resolution to achieve a minimal viable file size**MRC**: Profile designed to process mixed raster content**Archive**: Prepares a document for archiving in PDF/A format |
| OCR | `OCR` | Turn on and off optical character recognition for the job. All settings must be previously set up in the profile. If `true`, documents included in the job are processed to recognize any images as text (as appropriate). If `false`, no OCR is performed. |
| [Metadata](metadata.mdx) | `META.AUTHOR` | The author of the document |
| [Metadata](metadata.mdx) | `META.TITLE` | The title of the document |
| [Metadata](metadata.mdx) | `META.SUBJECT` | The subject of the document |
| [Metadata](metadata.mdx) | `META.KEYWORDS` | Keywords that apply to the document |
| Document settings | `PDF.LINEARIZE` | Enable or disable linearization of the output PDF. |
:::note
You can also set [extended metadata properties](metadata.mdx#extended-properties) apart from the standard metadata properties.
:::
### Document options
Document options apply only to a specific input. It allows you to determine specific properties based on an individual document, rather than as a global setting (either determined by the job or the profile). Any subsequent jobs processed with the workflow profile use the profile's default settings.
| Type | Option | Description |
| --- | ---- | --- |
| Document property | `DOC.PASSWORD` | Set the password for the document. |
---
## Archive PDF/A-3 workflow
The Archive PDF/A-3 workflow is engineered specifically for preparing documents for archiving.
The features and processing steps are identical to the ([Archive PDF/A 2](./README.mdx#archive-pdfa-workflows)).
However, the PDF/A-3 format allows additional features regarding embedded files.
In particular, attachments that are not conforming to PDF/A.
The unconverted original files are embedded as *Source* in the converted PDF. This allows for more flexibility, preserving the original file while still ensuring the document is archive-ready.
The Archive PDF/A-3 workflow supports the following features:
- Conversion to PDF/A-3 format (PDF/A-3b, PDF/A-3u, and PDF/A-3a)
- Compression and optimization of PDF/A structure (optional)
- Office conversion (optional)
- Optical character recognition (optional)
- Digital signatures (optional)
:::info Conformance levels
The Conversion Service supports Basic (PDF/A-3b), Unicode (PDF/A-3u), and accessibility (PDF/A-3a) conformance levels.
All conformance levels are incremental; the subsequent conformance level includes the requirements of the previous level and other additional requirements.
For example, all level U (Unicode) PDF/A-3 documents are **also valid level B (Basic) documents**.
The Archive PDF/A-3 workflow automatically tries to converts to the **highest conformance level** for PDF/A-3 (usually, PDF/A-3a). If the input document is PDF/A-3b or a PDF without structure information, it tries to converts the document to PDF/A-3u. If it is unable to convert to this level, it converts to PDF/A-3b or ends in failure.
:::
## Supported file formats for Archive PDF/A-3 workflow
The Archive PDF/A-3 workflow supports the following file formats:
| Content type | File type |
|------------------|--------------------------------------------------------------------------------------|
| Document formats | PDF 1.x, PDF 2.0, PDF/A-1, PDF/A-2, PDF/A-3 |
| Image formats | JPEG, JPEG200, TIFF, BMP, GIF, JBIG2, PNG, HEIC, HEIF, WebP, JFIF |
| Email | EML, MSG (without encryption) |
| Word | DOC, DOT, DOCX, DOCM, DOTX, DOTM, RTF, XML (WordprocessingML 2003) |
| Excel | XLS, XLT, XLSX, XLSM, XLTX, XLTM, XML (SpreadsheetML 2003) |
| PowerPoint | PPT, PPS, PPTX, PPTM, PPSX, PPSM |
| OpenOffice | ODT, ODS, ODP |
| Other | CSV, HTML, HTM (prepared for archiving), TXT, XML, ZIP (without password protection) |
:::info Note on OpenOffice formats
PDF conversion of OpenDocument Format depends on the rendering in Microsoft Word, Excel or PowerPoint. In particular, visual differences may occur with tables and tabs. The visual differences caused by the rendering of shapes are usually not acceptable.
:::
:::info Note on HTML format
HTML documents need to be self-contained (layout information and images are either inline or available on the web) and suited for portrait page layout. JavaScript content is disabled during processing.
:::
:::info Note on XML format
Layout information and images need to be available on the web.
:::
The conversion of most file formats is enabled by default in the Convert mode.
## Configure the workflow
The workflow's profile offers a fine-grained configuration of how files are converted.
### Convert mode for child documents (attachments)
This extends the Convert mode of the [PDF/A-2](pdfa_2.mdx#convert-mode-for-child-documents-attachments) workflow with PDF/A-3 features.
Specifically, the PDF/A-3 standard allows to embed child documents *As Is*, i.e. without converting them to PDF/A. For example, by default Office files are converted to PDF/A-3, images are used as-is, and executables are removed.
### Collect mode
This is the same as the Collect mode of the [PDF/A-2](pdfa_2.mdx#collect-mode) workflow.
However, in the PDF/A-3 workflow, it is common to choose the *As Is* Convert mode for some child document types.
Therefore, the use of the **Merge** collect mode is strongly discouraged, because it is limited to PDF documents (review [Collect mode](pdfa_2.mdx#collect-mode)).
Instead, the **Collection or Single Document** and **Attach** collect modes are recommended.
Refer to the documentation panel of the Conversion Service Configurator for a detailed description of the available collect modes.
### Attach Source Document
The source document (original document) can be attached. The configuration allows for each file type to decide if the source document should be attached or not.
By default, the source documents for Office files are attached. Note that this may increase the file size of the result substantially.
### Attach Conversion Report
All events of a conversion can be written to a report file and attached to the result document.
### Linearization
Linearization internally restructures document content for faster loading and rendering in web browsers. However, linearization has trade-offs such as increased file size and a limited effect on rendering performance. Use PDF linearization when you need to load the first page of a PDF fast on the web.
The Conversion Service doesn't support linearization of attached documents (child documents).
:::info
Although linearization provides fast, page-by-page loading over a network connection, it is not recommended for all use cases as it can considerably increase file size and has a limited effect.
:::
## Job and document options for the PDF/A-3 workflow
The PDF/A-3 workflow lets you use [job and document options](../configure/configure-job-and-document-options.mdx) to pass job and document-specific values to be used when processing documents using the workflow.
:::note
Job and document options you pass at runtime affect only the current job. When you change a setting of the job or document options, that change applies only to the current job. For the next job, the workflow reverts to the profile settings (saved default) unless you pass job or document options again.
:::
### Job options
Job options apply to all documents processed in the same job. Any subsequent jobs processed with the workflow profile use the profile's default settings.
Type | Option | Description |
| --- | ---- | --- |
| Document compression and optimization | `OPTIMIZE` | Turn on or off document compression and optimization. All settings must be previously set up in the profile. If `true`, documents included in the job are compressed and optimized according to the optimization profile set in the profile settings. If `false`, no compression and optimization is performed. Documents can be optimized according to five profiles:**Web**: Compresses the file without affecting viewing quality on digital devices**Print**: Compresses the file without affecting print quality**Max**: Removes redundant data and reduces image resolution to achieve a minimal viable file size**MRC**: Profile designed to process mixed raster content**Archive**: Prepares a document for archiving in PDF/A format |
| OCR | `OCR` | Turn on and off optical character recognition for the job. All settings must be previously set up in the profile. If `true`, documents included in the job are processed to recognize any images as text (as appropriate). If `false`, no OCR is performed. |
| [Metadata](metadata.mdx) | `META.AUTHOR` | The author of the document |
| [Metadata](metadata.mdx) | `META.TITLE` | The title of the document |
| [Metadata](metadata.mdx) | `META.SUBJECT` | The subject of the document |
| [Metadata](metadata.mdx) | `META.KEYWORDS` | Keywords that apply to the document |
| Document settings | `PDF.LINEARIZE` | Enable or disable linearization of the output PDF. |
:::note
You can also set [extended metadata properties](metadata.mdx#extended-properties) apart from the standard metadata properties.
:::
### Document options
Document options apply only to a specific input. It allows you to determine specific properties based on an individual document, rather than as a global setting (either determined by the job or the profile). Any subsequent jobs processed with the workflow profile use the profile's default settings.
| Type | Option | Description |
| --- | ---- | --- |
| Document property | `DOC.PASSWORD` | Set the password for the document. |
---
## Sign workflow
This workflow is engineered specifically for signing archived documents without removing the existing signatures.
:::tip
To learn about specific configuration options, review **[Configure signature](../configure/configure-signature/README.mdx)** documentation.
:::
The Sign workflow supports the following features:
- Digital Signature (mandatory)
## Supported file formats for Sign workflow
This workflow supports these file formats:
| Content type | File type |
|------------------|--------------------------------------------------------------------------------------|
| PDF formats | PDF/A-1, PDF/A-2, PDF/A-3 |
:::caution Note on PDF formats
Non-archival PDF formats are not supported.
Use the [Archive PDF/A-2](../workflows/pdfa_2.mdx) workflow to archive PDF into PDF/A format and sign the documents. You can configure digital signatures in the profile configuration of the Archive PDF/A-2 workflow.
:::
## Features and limitations
Compared to the other workflows, this workflow has the following features and limitations:
### Sign only
In the Sign workflow it's manadatory to configure digital signature, otherwise the Conversion Service returns a warning.
### Set metadata
The signature is not applied on the PDF metadata section so you can add new signature meanwhile changing the metadata of the document.
:::note
In an appropriate PDF reader you can see the previous signed version with the original metadata.
:::
## Job and document options for the Sign workflow
The Sign workflow lets you use [job and document options](../configure/configure-job-and-document-options.mdx) to pass job and document-specific values to be used when processing documents using the workflow.
:::note
Job and document options you pass at runtime affect only the current job. When you change a setting of the job or document options, that change applies only to the current job. For the next job, the workflow reverts to the profile settings (saved default) unless you pass job or document options again.
:::
### Job options
Job options apply to all documents processed in the same job. Any subsequent jobs processed with the workflow profile use the profile's default settings.
| Type | Option | Description |
| --- | ---- | --- |
| **[Metadata](metadata.mdx)** | `META.AUTHOR` | The author of the document |
| **[Metadata](metadata.mdx)** | `META.TITLE` | The title of the document |
| **[Metadata](metadata.mdx)** | `META.SUBJECT` | The subject of the document |
| **[Metadata](metadata.mdx)** | `META.KEYWORDS` | Keywords that apply to the document |
:::note
You can also set [extended metadata properties](metadata.mdx#extended-properties) apart from the standard metadata properties.
:::
### Document options
Document options apply only to a specific input. It allows you to determine specific properties based on an individual document, rather than as a global setting (determined by the job or the profile). Use the default profile settings for any subsequent jobs processed with the workflow profile.
| Type | Option | Description |
| --- | ---- | --- |
| Document property | `DOC.PASSWORD` | Set the password for the document. |
---
## Stamp and annotation
Stamping and annotations add small bits of content to the existing content of PDF pages. A stamp is a fixed visual mark placed on a page, whereas an annotation is an interactive element that lets users to move, resize, or remove the annotations if they are allowed to edit the resulting document in their PDF viewer. In the Conversion Service Configurator, you can configure the following types of **stamps and annotations**:
- Text
- Image
- Barcode
:::info
Add and configure stamps and annotations within a workflow by enabling **Stamp and Annotation** toggle in a specific profile configuration. For more details and procedures, review **[Configure stamping](../configure/configure-stamping.mdx)**.
:::
## Workflow specific settings
Some workflows have special configuration settings for stamping. For example, you can configure the exact page on which you want to apply the stamp.
- For [Archive PDF/A-1](pdfa_1.mdx), [Archive PDF/A-2](pdfa_2.mdx), [Archive PDF/A-3](pdfa_3.mdx) and [Conversion](conversion.mdx) workflows, you can select the page where the stamp or annotation will be applied. There are three options:
- **All**: The stamp is applied to all pages of all documents.
- **First**: The stamp is applied to the first page of the main output document. An error is triggered if the resulting document is a collection.
- **Last**: The stamp is applied to the last page of the main output document. An error is triggered if the output document is a collection.
- In the [Dossier](dossier.mdx) workflow, you can choose to stamp of the table of contents or leave it without a stamp.
---
## Archive TIFF workflow
Learn how to automatically convert documents, images, and office files to TIFF format suitable for archiving using the Archive TIFF workflow in the Conversion Service. The Archive TIFF workflow is engineered specifically to prepare documents for archiving.
The Archive TIFF workflow supports the following features:
- Single-page or multipage TIFF output
- Office conversion (optional)
- Stamping (optional)
## Supported file formats for Archive TIFF workflow
The Archive TIFF workflow supports the following file formats:
| Content type | File type |
|------------------|--------------------------------------------------------------------------------------|
| PDF formats | PDF 1.x, PDF 2.0, PDF/A-1, PDF/A-2, PDF/A-3 |
| Image formats | JPEG, JPEG200, TIFF, BMP, GIF, JBIG2, PNG, HEIC, HEIF, WebP, JFIF |
| Email | EML, MSG (without encryption) |
| Word | DOC, DOT, DOCX, DOCM, DOTX, DOTM, RTF, XML (WordprocessingML 2003) |
| Excel | XLS, XLT, XLSX, XLSM, XLTX, XLTM, XML (SpreadsheetML 2003) |
| PowerPoint | PPT, PPS, PPTX, PPTM, PPSX, PPSM |
| OpenOffice | ODT, ODS, ODP |
| Other | CSV, HTML, HTM (prepared for archiving), TXT, XML, ZIP (without password protection) |
:::caution Note on OpenOffice formats
PDF conversion of OpenDocument Format depends on the rendering in Microsoft Word, Excel, or PowerPoint.
In particular, the conversion can result in visual differences in tables and tabs.
The visual differences caused by the difference in rendering of shapes are usually not acceptable.
:::
:::caution Note on HTML format
HTML documents need to be self-contained (layout information and images are either inline or available on the web) and suited for portrait page layout.
JavaScript content is disabled during processing.
:::
:::caution Note on XML format
Make the layout information and images defined as links in the XML files available on the web to incorporate them into the TIFF output.
:::
The conversion of most file formats is enabled by default in the profile's Convert mode for child documents (attachments).
## Features and limitations
Compared to the other workflows, this workflow has the following features and limitations:
### Multi or single-page conversion
TIFF format supports multiple pages in one file. You can configure the multipage output for each individual input document using the `MULTIPAGE` option. When you disable the multipage option, the output is one file for each page of the input document.
### Compression
The TIFF workflow supports multiple different compression types. You can set the compression type of and quality depending on the input image type.
### Collect mode
The TIFF standard does not allow embedded files. Therefore, **Merge** is the only collect mode configuration available.
## Job and document options for the TIFF workflow
The TIFF workflow lets you use [job and document options](../configure/configure-job-and-document-options.mdx) to pass job and document-specific values to be used when processing documents using the workflow.
:::note
Job and document options you pass at runtime affect only the current job. When you change a setting of the job or document options, that change applies only to the current job. For the next job, the workflow reverts to the profile settings (saved default) unless you pass job or document options again.
:::
### Job options
Job options apply to all documents processed in the same job. Use the default profile settings for any subsequent jobs processed with the workflow profile.
| Type | Option | Description |
| --- | ---- | --- |
| [Multi or single page output](#multi-or-single-page-conversion) | `MULTIPAGE` | Turn on or off multipage output. If `true`, documents included in the job are outputted as a single file with multiple pages. If `false`, documents included in the job are outputted as single-page files. |
| [Compression](#compression) | `QUALITY` | The compression quality is applied for each of the compression types. |
### Document options
Document options apply only to a specific input. It allows you to determine specific properties based on an individual document, rather than as a global setting (determined by the job or the profile). Use the default profile settings for any subsequent jobs processed with the workflow profile.
| Type | Option | Description |
| --- | ---- | --- |
| Document property | `DOC.PASSWORD` | Set the password for the document. |
---
## Digital signature basics
import useBaseUrl from '@docusaurus/useBaseUrl';
Learn about digital signatures, differences between electronic and digital signatures, public key infrastructure, certificate authorities, and electronic signature laws and regulations.
:::tip
Pdftools software that lets you manage digital signatures:
- The [Conversion Service](../../conversion-service/). Review [Configure signature](../../conversion-service/configure/configure-signature/).
- The [Pdftools SDK](../../pdf-tools-sdk/). Review [Sign PDF documents](../../pdf-tools-sdk/sign-and-secure/sign/).
:::
## The purpose of digital signatures
A digital signature can satisfy the legal requirements of a handwritten signature but also offers significant time and resource savings.
When comparing digital signatures to handwritten signatures, we can mention the following benefits:
- Physical presence of the signatory is not required.
- Postage prices for signing many documents with signers in different locations can be high.
- There is no need to print documents only to sign them.
:::note
In some legal cases, the signature is not binding, and an additional physical signature on paper is required.
:::
Applying an electronic signature is very similar to a handwritten signature:
A person reads a document and signs it with its name.
A valid electronic signature is a section of data embedded in the document. You can use this signature to:
- Ensure the document's integrity and that it wasn't tampered with.
- Authenticate the signer of the document.
- Prove the file has existed before the date.
## Difference between electronic signature and digital signature
You may have noticed that the terms **electronic signature** and **digital signature** are often used interchangeably. Still, these terms carry different meanings. Electronic signature is a general umbrella term for various types of signatures. Digital signature is a subtype of electronic signatures with specific technical improvements and agreed legal requirements they meet compared to electronic signatures. In short, all digital signatures are electronic signatures, but not all electronic signatures are digital signatures.
:::info
While all digital signatures are electronic signatures, not all electronic signatures are digital signatures.
Note that these terms can have **country-specific differences** in translation, interpretation, and legal acceptance.
:::
### Electronic signature
In general, an electronic signature is data in electronic form attached to other electronic data in a document.
In its simplest form, an electronic signature can be an image of your signature that you include in a document (for example, PDF, RTF, DOC, DOCX). Even your email signature is an electronic signature.
### Digital signature
A digital signature is created by applying a **cryptographic algorithm** to the document, which provides additional security. This cryptographic algorithm requires personal information (your **private key**). This information relies on an advanced **Public Key Infrastructure (PKI)** method. Cryptographic signatures follow strict regulations such as the **European Union eIDAS** or **Swiss ZertES**, providing a trusted, secure, and auditable signature.
## Public key infrastructure
Public key infrastructure is a framework for securing communication over the internet.
It verifies the identity of parties involved in a transaction and encrypts or decrypts the data exchanged between them.
Two keys are necessary to verify, encrypt, and decrypt the data:
- **Public key**
- **Private key**
Both keys are explained in the following sections.
### Public key
The public key is a large numerical value used to encrypt data and is **part of your certificate**.
Your certificate is a file with an extension such as `.cer,` `.pem`, or `.crt` that stores information about the owner and contains the public key.
:::note
This file format cannot store private keys and can store only one certificate, [X.509](https://en.wikipedia.org/wiki/X.509) (the standard defining the context and layout of public key certificates).
:::
:::tip
Your public key information is not sensitive; you can share it with others.
:::
### Private key
The private key is a large numerical value used in an encryption algorithm to decrypt data. It is **part of your Digital ID**, which could have different representations.
You can store it in a physical smart card, an HSM device, or a file on your disk.
:::info
In the case of smart card authentication, your user credentials, which are your public and private keys and certificate, are stored on a smart card. You are authenticated when you insert a card into a card reader and then provide a PIN.
:::
Smart card example
Smart card example
1. Ryan has a smart card containing a private key. Ryan signs a document with the smart card and then sends the document to Julia.
The private key is kept secret and remains with Ryan because, as the smart card owner, only he can sign the document with that private key.
2. Along with the document, Ryan can create a certificate containing the public key they make available to Julia.
You can share the certificate safely with anyone, as it only contains the means to validate a signed document.
3. When Ryan publicly shares their certificate, Julia receives the document and can verify that Ryan, the private key owner, signed it.
Julia can be sure that nobody modified the document since Ryan signed it.
The certificate contains information about the signee. It states who owns the private key that belongs to that certificate.
### Digital ID
A digital ID is a file that proves your identity details, similar to a driver's license or a passport.
Digital ID contains **two important sections**
- Your **private key** to decrypt data.
- When you sign PDFs, you use the private key to apply your digital signature.
- Your **certificate contains your public key** to encrypt data.
- You can distribute the certificate to those who want to validate your signature or identity.
:::tip Store your digital ID in a safe place
Your digital ID contains your private key, which others can use to sign in your name.
:::
:::note
Digital ID files, also called **PKCS#12** files, have the **.pfx** (Windows) or **.p12** (macOS) extensions.
They can be used interchangeably between operating systems.
This archive file format stores many cryptographic objects in a single file.
:::
### Chain of trust (certification path)
The chain of trust refers to your certificate and its link to a trusted **certificate authority (CA)**.
Certificates (or signatures) can be verified based on other certificates.
We can trace back the verification to the public keys of root authentication providers, showing that many people know and accept these keys.
CAs operate on a hierarchical basis. At the top of this hierarchy are the Root Certificate Authorities (Root CAs), responsible for verifying and issuing certificates to subordinate certificate authorities.
These Root CAs are trusted entities worldwide and form the foundation of the public key infrastructure.
The **trust chain**, which includes all issuer certificates and the root certificate, must be embedded in the digital signature.
The trust chain ensures that the signature can be verified by any party that trusts the Root CA.
Embedding the trust chain in the signature requires all issuer certificates, including the root certificate.
## Certificate authorities
A certification authority (CA) is an entity that stores, signs, and issues digital certificates (digital IDs) that certify the ownership of a public key. For more details, review the previous section [Chain of trust (certification path)](#chain-of-trust-certification-path).
:::info Important
A digital signature or digital ID is commonly known as a **digital certificate.**
:::
:::note
It's important to **distinguish between X.509 certificate files** in `.cer` or `.crt` format **and combined certificates that contain private keys** in `.p12` or `.pfx` format.
:::
### Verify the signee
In X.509 certificates, the certificate path describes a third party, known as a certification authority, which verifies the validity of the information in the certificate connected to a specific person.
Certification authorities are responsible for checking the identity of the person who requests a certificate.
If a **trusted CA** issued a certificate, you can trust it also.
### Trusted certificate authorities
There are two primary sources for verifying whether a trusted CA issued the certificate. If the Root certificate is trusted, you can trust the certificate.
#### The Adobe Approved Trust List (AATL)
You can trust that the [listed CAs and Trust Service Providers (TSPs)](https://helpx.adobe.com/acrobat/kb/approved-trust-list1.html) comply with global legal and regulatory requirements, including the EU eIDAS regulation.
You can also find Digital ID providers that are approved outside of the EU.
#### European Union Trusted Lists (EUTL)
The [European Union Trust Lists are public lists](https://helpx.adobe.com/document-cloud/kb/european-union-trust-lists.html) containing more than 200 active and former trust service providers (TSPs) who,
according to their accreditation, best meet the eIDAS electronic signature regulation requirements.
Once you get your digital ID from one of the providers below, securely signing documents becomes easy.
### Private certificate authorities
With a Windows Server, you can create a CA to manage issued and pending certificates through a web interface.
This is a fine solution for internal usage. You can access your Certificate Services through Active Directory.
In the following picture, **PDF Tools RootCA2** is the private CA, and **PDF Tools Support** is the certificate issued.
If you share your signed PDF with a third party that doesn't have the certificates installed on their local machine, they are prompted with warnings at the signature panel and the certificate properties.
If you trust this person, there are two ways to accept their certificate:
- Add the certificate through the Adobe Acrobat Reader interface.
- Add it manually to your Windows Certificate Store.
### Self-signed certificate
A root CA is not always necessary. You can create a custom digital ID and sign documents with a self-signed certificate.
The following sections, [Create digital ID with Adobe Reader](#create-digital-id-with-adobe-reader) and [Create digital ID with PowerShell](#create-digital-id-with-powershell) explain two ways to create a self-signed certificate.
#### Create digital ID with Adobe Reader
You can follow the steps in [Create a self-signed digital ID](https://helpx.adobe.com/acrobat/using/digital-ids.html#create_a_self_signed_digital_id) in Adobe documentation.
By the end of this process, you will create a `.pfx` file.
This file contains the private key and the X.509 certificate (which includes the public key).
#### Create digital ID with PowerShell
1. Create a certificate and install it on your local machine (Personal Certificate Store):
```powershell
New-SelfSignedCertificate -certstorelocation cert:\localmachine\my -dnsname "TestCert"
```
2. Secure your certificate:
```powershell
$pwd = ConvertTo-SecureString -String "Password" -Force -AsPlainText
```
3. Export the certificate with a password:
```powershell
Export-PfxCertificate -cert cert:\localMachine\my\5663345E048BFD700866449B286F777DAB8D3C12 -FilePath root-authority.pfx -Password $pwd
```
- Replace the example thumbprint `5663345E048BFD700866449B286F777DAB8D3C12` with the one you generated.
:::info Important!
In the Conversion Service, you can't use the `.pfx` file directly, but you can install it to the Windows certificate store under the user who runs the application, which is the SYSTEM user.
:::
### Certificate revocation information
You can revoke your digital certificate when you lose it. As a result, anyone who finds or acquires your original certificate cannot use it to sign on your behalf illegally.
In this case, it's getting invalidated before the expiry date. All the signatures you created before that time remain valid, but the ones you created later will be invalid.
The signature ensures that the certificate was valid when the document was signed (due to the embedding of the OCSP/CRL response).
#### Online certificate status protocol (OCSP)
[OCSP](https://datatracker.ietf.org/doc/html/rfc2560) is a protocol for interactively checking the revocation of a single certificate.
It can provide more timely revocation information than CRLs.
#### Certificate revocation list (CRL)
A [CRL](https://datatracker.ietf.org/doc/html/rfc3280) is a list of digital certificates the CA revoked before their scheduled expiration date.
The CRL is an online service where you can check if a certificate is valid.
## Electronic signature laws and regulations (EU)
The strength and reliability of the signature you want to use are tied to your requirements. CA's responsibility is to provide the desired level of strength and reliability.
### Simple electronic signature
Simple electronic signatures have no legal significance. A simple electronic signature can be a cryptographic signature. A cryptographic signature is generated using a digital certificate, but the certificate is not from a trusted Certificate Authority.
It can be a self-signed certificate, which means it doesn't have an issuer or can be created by some private CA like a company (for example Pdftools) that issues a new certificate.
A simple electronic signature cannot verify the identity of the signer.
Using a simple electronic signature brings the following advantages:
- The signature ensures the integrity of the signed content.
- Subsequent changes in the data are detectable.
### Advanced electronic signature (AdES)
Legally, the advanced electronic signature is similar to a company stamp. It's used for mass signature.
:::note
While legally binding in many contexts, AdES is not identical in its legal status or formal recognition to an official handwritten signature.
:::
A trust service provider or CA (such as SwissSign) issues digital certificates for AdES e-signature type, typically after verifying an individual's identity.
Certificates in this category meet the requirements of **eIDAS**, which means they are regulated by law and have strict processes.
:::tip
To receive an advanced certificate, the owner must prove their identity, for example, by physically visiting the CA and presenting their passport.
The owner can be a legal person or entity.
:::
An advanced certificate contains the owner's name, the name of the CA, the period of validity, and other information.
The AdEs brings the following advantages over a simple electronic signature:
- Capable of identifying the signatory, who can be a legal person or an entity provided by a trusted CA.
- You can acquire Certificate revocation information from an online service. Embed the valid response (for example: valid, revoked) in the signature (OCSP, CLR).
- Protected private key storage.
#### OCSP and CRL
Embedding revocation information is optional but recommended when applying advanced (AES) or qualified electronic signatures (QES).
The signing certificate includes the revocation information and all certificates of its trust chain.
Therefore, the same message may present both OCSP responses and CRLs.
However, embedding revocation information increases the file size (usually around 20 kB) and requires an external request to a validation service, which may delay the signing process.
### Qualified electronic signature (QES)
The requirements for a **qualified certificate** and qualified signatures vary by country. You can't make mass signatures with them.
:::info
In many European Countries, a qualified electronic signature (QES) is equivalent to a handwritten signature.
:::
Nobody can sign the document without the user's interaction. As a result, the QES is equal to a handwritten signature, meaning that you can apply only one signature at a time.
:::info Examples
The QES is a signature created by a qualified electronic signature creation device (QESCD).
For example, a physical smartcard held by the signer with an associated PIN code or hardware security module operated remotely by a qualified trust service provider (QTSP) in the cloud.
You have to enter the PIN code manually. This signature can also be approved from a mobile phone.
:::
A qualified electronic signature is similar to an [advanced electronic signature](#advanced-electronic-signature-ades) but has higher requirements. The main differences are:
- The key storage must ensure that the user approves the signature manually when you sign the document.
- A time-stamp can be required to ensure the integrity of the signing time.
- Supports QES useful for legal processes.
#### Qualified certificate
Qualified certificates for electronic signatures issued by a Qualified Trust Service Provider (QTSP).
A QES based on a qualified certificate issued in one EU Member State is recognized in all other EU Member States.
#### TSP and QTSP
Generally, there are two types of trust services:
- Trust Service Provider (TSP)
- Qualified Trust Service Provider (QTSP)
Only a QTSP can provide a qualified version of the services, which can be described as additional security.
## Types of electronic signatures
There are different types of electronic signatures that Pdftools provides.
### Document signature
The most usual type of signature is a document signature, also called an approval signature. You need a digital certificate to create this type of signature.
The main responsibilities are:
- Ensure the integrity of the document.
- Authenticate the signer's identity.
:::note
You can modify and save signed documents by incremental updates. The document's state can be recreated as it existed at the time of signing.
:::
Optional responsibilities:
- Optional visual appearance in the document.
- Optional time-stamp provided by a time-stamp authority (TSA).
- Optional long-term validation (OCSP, CRL).
- You can add multiple signatures.
#### Multiple signatures in archived documents
Many types of documents that require digital signatures also require archiving.
PDF/A conformance is often necessary for archiving to ensure the file is not corrupt and its visual appearance is well-defined and reproducible.
However, during the conversion process from PDF to PDF/A, signatures could be removed from the file before it is converted to PDF/A for archival.
Even if your PDF is archived, the signature can be removed if it doesn't conform to the best possible conformance level.
Before any digital signatures are applied, archive the files in PDF/A format.
:::info
When you archive files in the Conversion Service using the Archive PDF/A workflow, the service first removes the previously applied digital signatures before archiving a file.
:::
:::tip Suggestion
Signature workflow lets you add additional signatures to your archived PDF, even if it doesn't conform to the best possible conformance level.
:::
### Document certification signature
:::note
You can't add this type of signature to your document with the Conversion Service. However, leverage the document certification signature with the Pdftools SDK.
:::
It's also called the Modification Detection and Prevention signature (MDP).
A document can contain only one MDP signature, which must be the first. Other signature types can be present.
The document certification signature is similar to the [document signature](#document-signature), but the author can define what changes they allow and which modifications they prevent. The main differences are:
- Document certification signature detects changes.
- Displayed differently in Adobe Reader.
- You can add only one MDP signature.
- It's to contain a signature visual appearance, time-stamp, or long-term validation.
### Document time-stamp signature
A time-stamp signature proves that the document existed at a specific time and protects its integrity.
You can apply one or more Document Time-stamp signatures. A signed document can be modified and saved incrementally.
:::info
You can use time-stamp signatures separately, but including a time-stamp signature in document signatures is common.
:::
Main responsibilities:
- It's a simple signature that ensures the integrity of the document. In Adobe Reader, it's displayed as a watch symbol.
- It's a Proof of Existence (PoE).
#### Time-stamp authorities
A time-stamp authority (TSA) provides trusted, cryptographically secure time-stamp information.
This time-stamp information can be used to apply a digital time-stamp to a document, which verifies that the document existed at a point in time and that its content wasn't changed.
A time-stamp signature does not require a local signing certificate. Instead, the time-stamp signature requested from the time-stamp authority is embedded into the document.
However, a cryptographic provider that supports time-stamp signatures is required.
### Unsigned signature field
:::note
You can't add this type of signature to your document with the Conversion Service, but you can leverage it with the Pdftools SDK.
:::
You can set a position where you expect to have a signature.
## PaDES Standard - PDF Advanced Electronic Signatures
PAdES is a technical standard for PDF documents and refers specifically to restrictions and extensions of electronic signatures.
With PAdES, you can provide a unique electronic signature.
:::note
The 'advanced' part of the name refers to the upgraded security and validation methods it provides for electronic document signatures.
Don't confuse the 'advanced' with the 'advanced' part in the AdES signatures.
:::
#### History of PaDES
- Before this standard, signatures varied and were incompatible across different software.
- The European Telecommunications Standards Institute (ETSI) published the PaDES technical standard in 2009, which makes signatures interoperable between different software.
- The PaDES was updated in 2011 and later in 2015 to the European norm ETSI EN 319 142. The update provided an improved specification that is still widely accepted.
:::note
Signatures that you can create with the Conversion Service provide compatible standards.
:::
The following table informs about the historical evolution of the names of these standards. The first column is the latest standard defined in the ETSI EN 319 142 norm with four baseline signature levels recommended by the PAdES European standard. The second, third, and fourth columns display previously defined standards. Although the names differ based on the standards, they have similar meanings but also some slight differences:
| ETSI EN 319 142 | ETSI TS 102 778 | ETSI TS 103 172 | ISO 14533-3 |
|-----------------------------------|-----------------|-----------------|--------------|
| **[PAdES B-B](#pades-b-b)** | PAdES-BES | PAdES B-Level | - |
| **[PAdES B-T](#pades-b-t)** | PAdES-BES | PAdES T-Level | PAdES-T |
| **[PAdES B-LT](#pades-b-lt)** | PAdES-BES | PAdES LT-Level | PAdES-A |
| **[PAdES B-LTA](#pades-b-lta)** | PAdES-LTV | PAdES LTA-Level | PAdES-A |
### PAdES B-B
PAdES B-B is a basic digital signature that contains information about the document's integrity and the signee's authenticity.
### PAdES B-T
PAdES B-T is a digital signature with a time-stamp token.
### PAdES B-LT
PAdES B-LT is a digital signature with a time-stamp token and long-term validation data.
#### Advantages of long-term signature
Every signature expires. The period after which signatures expire is usually five years. You cannot see if the certificate was revoked when a signature validity period expired.
To solve the problem, you can embed validation data that you can get from your online service.
If someone looks at the document after the signature has expired, they can see the validation data to check the certificate was not revoked when the signature was created.
If your signature is not long-term, you can only see if it was revoked until it is valid.
:::info
You can configure the Conversion Service to embed long-term validation (LTV) information into a document during the signing.
This setting attempts to embed revocation information such as OCSP and CRL.
A validation service provides the revocation information at the time of signing and acts as proof the certificate was valid at the time of signing.
:::
### PAdES B-LTA
PAdES B-LTA is similar to PAdES B-LT but adds a document time-stamp at the end of the document
:::note
The time-stamp improves the data protection. The original algorithm can become obsolete, and attackers (such as hackers) may abuse your signature.
Included time-stamp can ensure that a specific algorithm needs to be updated.
:::
## Signature validation
Validate signatures using sources such as certificates, Online Certificate Status Protocol results, and Certificate Revocation List results.
These sources can be embedded in the PDF file, stored on the local machine, or downloaded from the issuer.
Three items need to be validated:
1. Trust chain
2. Revocation information (optional)
3. time-stamp (optional)
---
## PDF/A specification
PDF/A is an [ISO standard](pdf-standards.mdx) for using the PDF format for long-term archiving of electronic documents.
## PDF/A-1
PDF/A-1 (ISO 19005-1) is based on PDF 1.4 (Acrobat 5). In addition to the PDF 1.4 requirements, it specifies that documents must be kept self-contained and suitable for long-term archival.
Key differences between PDF 1.4 and PDF/A-1
- Encryption may not be used.
- If device-dependent color space is used (i.e. DeviceRGB, DeviceCMYK, DeviceGray), a corresponding color profile must be embedded.
- Fonts used for visible text must be embedded.
- Transparency may not be used.
## PDF/A-2
PDF/A-2 is described in ISO 19005-2. It is based on ISO 32000-1, the standard for PDF 1.7. PDF/A-2 is meant as an extension to PDF/A-1. The second part complements the first part and does not replace it.
Key differences between PDF/A-1 and PDF/A-2
- The list of compression types has been extended by JPEG2000.
- Transparent contents produced by graphic programs are allowed.
- Optional contents (also known as layers) can be made visible or invisible.
- Multiple PDF/A files can be bundled in one file (collection, package).
- The additional conformity level U (Unicode) allows for creating searchable files without having to fulfill the strict requirements of the conformity level A (accessibility).
- File size can be reduced using compressed object and XRef streams.
Any documents that contain these features (particularly, layers or transparency) should be converted to PDF/A-2 rather than PDF/A-1.
## PDF/A-3
PDF/A-3 is described in ISO 19005-3. It is based on ISO 32000-1, the standard for PDF 1.7. PDF/A-3 is an extension to PDF/A-2. The third part complements the second part and does not replace it.
Key differences between PDF/A 2 and PDF/A 3
- Files of any format and conformance may be embedded. Embedded files need not be suitable for long-term archiving.
- Embed files can be associated with any part of the PDF/A-3 file.
---
## PDF standards
PDF (Portable Document Format) is a file format developed to display documents (including text and images). It is designed to be software, hardware, and operating system independent. There are several ISO standards that cover PDF:
- [Standard file format](#standard-file-format)
- [Specialized uses](#specialized-uses)
## Standard file format
Developed by Adobe as a proprietary format ([Adobe PDF 1.0](https://opensource.adobe.com/dc-acrobat-sdk-docs/pdfstandards/pdfreference1.0.pdf)) in 1992, PDF was designed to be a digital form for representing electronic documents. The format enable users to exchange and view electronic documents independent of the environment in which they were created or the environment in which they are viewed or printed.
PDF files may contain a variety of content:
- flat text
- graphics (images)
- logical structuring elements such as document outlines (table of contents)
- interactive elements such as annotations and form fields
- layers
- rich media, including video content
- three-dimensional objects using U3D or PRC
- other data formats
The PDF specification also provides for encryption and digital signatures, file attachments, and metadata to enable workflows requiring these features.
### PDF 1.7 (ISO 32000-1)
To further increase acceptance of PDF as a format, Adobe Systems submitted [PDF Version 1.7](https://opensource.adobe.com/dc-acrobat-sdk-docs/pdfstandards/PDF32000_2008.pdf) to the ISO for standardization. On July 1, [2008 ISO 32000-1 Document management — Portable document format - Part 1](https://www.iso.org/standard/51502.html) was published, turning PDF into an ISO standard.
The standard governs the software that creates the PDF files (confirming writers), software that reads PDF files and interprets the contents for display and interaction (conforming readers), and PDF products that read and write PDF files (conforming products).
### PDF 2.0 (ISO 32000-2)
Part 2 of the standard was put forward and approved by the ISO members. The list of changes contains more than 50 entries that refer to new features, improvements, and the clean-up of legacy issues that were present in the ISO 3200-1 standard. The new part of the standard mainly concerns rendering, transparency, digital signatures, metadata, and accessibility.
While this new part based on the preceding part, ISO 3200-1 continues to be current. However, the term conforming reader has been replaced and redefined as interactive PDF processor (software that reads and displays PDF content and interacts with the computer users to possibly modify and save the PDF file), PDF reader (software that reads existing PDF files and interprets their contents for display), and PDF writer (software that creates PDF files).
## Specialized uses
There are several technical specifications that determine the use of the PDF file format within specific applications:
- [Archiving](#pdfa---archive)
- [Exchange](#pdfx---exchange)
- [Variable and transactional printing](#pdfx---exchange)
- [Universal accessibility](#pdfua---universal-accessibility)
- [Engineering](#pdfe---engineering)
- [Healthcare](#pdfh---healthcare)
### PDF/A - Archive
The PDF/A standard (ISO 19005) defines the specifications for the archiving of digital documents. The PDF/A standard ensures that the visual appearance of electronic documents is preserved over time. This guarantees the readability of PDF/A-compliant documents. There are four versions of this standard.
### PDF/X - Exchange
PDF/X (ISO 15930) standardizes PDF as graphics files for printing. Several improvements and changes have been incorporated since it was first drafted in 2001. The current version is PDF/X-5.
### PDF/UA - Universal Accessibility
PDF/UA (ISO 14289) aims to make PDF documents accessible to people with disabilities. The standard includes guidelines on how PDF documents and the information elements they contain, such as graphics, text, multimedia elements, and form fields, must be made available so that they can navigate in the document, as well as receive the content via voice output.
### PDF/VT - Variable and transactional printing
Printing, packing, and franking transactional documents, whether they are essential business documents such as delivery notices, invoices and payment reminders or direct marketing letters sent out in sheer endless numbers, is a billion dollar market. The high numbers of print jobs and the requirements for short through-put times have not only led to the development of corresponding hardware like high-performance printers. Applications like Variable Data Printing (VDP) have been created in order to significantly cut the cost per printed item. These facts and the huge demand for a universal and standardized VDP solution have led to the development of PDF/VT.
### PDF/E - Engineering
PDF/E is a standard for technical documents in engineering, architecture and geo-information. The depiction of 3D objects and the exchange of plans/drawings shall be covered by the PDF/A-4e standard in the future.
### PDF/H - Healthcare
PDF/H is a guideline to regulate the creation, exchange, retention, and protection of healthcare-relevant information. PDF/H aims to close the gap between healthcare institutions and the consumer.
---
## Licenses of Pdftools products
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
# Licenses of Pdftools products
A valid license key is required to use the Pdftools products without limitations. Some products allow you to try them without a license key with watermarked results. See the list below for more details:
- **Pdftools SDK**: Watermarked results without a valid license key. Use a valid license key to remove the watermark.
- **Conversion Service**: Use a valid license key to try or work with the product.
- **PDF Viewer SDK**: Watermarked results without a valid license key. Use a valid license key to remove the watermark.
Other shell tools and SDKs:
- **PDF Toolbox SDK**: Use a valid license key to try or work with the product.
- **3-Heights SDK**: Use a valid license key to try or work with the product.
:::info
Do you need a full product license, a new license key, or an upgrade to your current license, or do you want to ask us anything else? Get in touch with our team through the [Contact page](https://www.pdf-tools.com/contact/).
:::
## Identifying a license key
This section helps you identify the product for which a specific license key can be used. To identify the product, compare your license key with the following examples:
```
```
:::info
- Value `PDFSDK` indicates that the license key belongs to Pdftools SDK.
- Values such as `V1` and `V4` change depending on the release version.
- To correctly validate the license key, include the angle brackets (`<>`) at the beginning and the end of the license key.
:::
```
4H-V6-JV0VY-GYQT3-4O73M-4CCWO-LXK0T-3J741-5TKUA
```
:::info
- The Conversion Service license key includes seven times five strings of alphanumeric characters (after `4H` and `V4` in the example above).
- Values such as `V1` and `V4` change depending on the release version.
:::
### Version 5
```
```
:::info
- Value `VIEWWEB` indicates that the license key belongs to the PDF Viewer SDK.
- Values such as `V1` and `V5` change depending on the release version.
- To correctly validate the license key, include the angle brackets (`<>`) at the beginning and the end of the license key.
:::
### Version 4
```
<4H,V4,VIEWWEB,A93H49S73H3QQSW99SFIR5V78NHVZS49BT3I6MD4L>
```
:::info
- Value `VIEWWEB` indicates that the license key belongs to the PDF Viewer SDK.
- Values such as `V1` and `V4` change depending on the release version.
- To correctly validate the license key, include the angle brackets (`<>`) at the beginning and the end of the license key.
:::
```
<4H,V4,TOOLSDK,LGKI1RJLSZUCXPFW4ETHG06N4>
```
:::info
- Value `TOOLSDK` indicates that the license key belongs to the PDF Toolbox SDK.
- Values such as `V1` and `V4` change depending on the release version.
- To correctly validate the license key, include the angle brackets (`<>`) at the beginning and the end of the license key.
:::
```
1-5IAXL-C3SJE-040YC-52T0J-CH98P-7KCY7-WLNF0
```
```
0-DHT83-AF2V1-31OG8-5U7FA-KXNBF-YQKS9
```
### License key activation
The process of activating and using a license key varies depending on the Pdftools product or version. See the respective product pages for detailed license information:
- [Pdftools SDK license](/docs/licenses/products/pdf-tools-sdk-license/)
- [Conversion Service license](/docs/licenses/products/conversion-service-license/)
- [PDF Viewer SDK license](/docs/licenses/products/pdf-web-viewer-license/)
- [PDF Toolbox SDK license](/docs/licenses/products/pdf-toolbox-sdk-license/)
- [3-Heights SDK licenses](/docs/licenses/products/3-heights-licenses/)
## Frequently asked questions
Questions commonly asked about licenses:
Error activating license (...) License already activated 1 times
Check that you haven't activated the license already on another machine. If so, deactivate the license on that machine.
To deactivate a license, see [Deactivation](https://www.pdf-tools.com/public/downloads/manuals/TechNoteLicenseKeys.pdf#page=11) section in Technical Note: License Keys.
If the error persists, contact [Pdftools Technical Support](https://www.pdf-tools.com/helpspot/index.php).
The license added in the License Manager stops working. A red cross appears and the software doesn't work.
Some Pdftools licenses need to be activated. The license works for approximately 10 days without activation. The date after which it requires activation is displayed in the License Manager in "Activation necessary starting...".
To activate a Pdftools license for PDF Toolbox SDK and PDF Viewer SDK, see [License activation](https://www.pdf-tools.com/public/downloads/manuals/TechNoteLicenseKeys.pdf#page=10).
To activate a 3-Heights product license, see [License activation](https://www.pdf-tools.com/public/downloads/manuals/TechNoteLicenseKeys3Heights.pdf#page=10).
Error connecting to the licensing server
**Pdftools SDK**
Check your network connection. If the SDK is unable to connect to the licensing server, the license (and the product usage) is blocked. To be able to activate licenses and use the product offline, you must have set up the [Licensing Gateway Service](/configure/README.mdx).
**PDF Toolbox and PDF Viewer SDK**
If the License Manager is unable to connect to the Licensing server, you can update, activate and deactivate the license offline. See [Offline usage](https://www.pdf-tools.com/public/downloads/manuals/TechNoteLicenseKeys.pdf#page=11).
If you use a proxy server, ensure that the proxy allows connections via HTTP CONNECT to `license.pdf-tools.com:443` and add the license server URL to an allow list in your firewall.
The licensing server returned an error: 301 Moved Permanently
You are using an old version of the License Manager (older than 4.11.18.0), which doesn't use HTTPS.
Update to the latest version of the License Manager and try to deactivate, activate, and update the license again.
Error updating the license key in the License Manager
Check that:
- The license key is still active for the product and hasn't expired. Evaluation licenses expire after 30 days.
- The format of the license key is correct for the product. See [Identifying a license key](#identifying-a-license-key) section.
- The license hasn't been installed on another machine. Otherwise, you need to deactivate the key on another machine before you can add it to the new machine.
- The license hasn't already been installed on a machine. An **Error storing key: File exists** message appears.
Error storing key: The license key has been manipulated
1. A typographical error in the license key. Try typing the key again. Make sure no blanks are added when copying the key.
2. Example key (1-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX) is used. The X character represents a numerical value and is not an active license key.
3. Download the key from [My PDF Tools Portal](https://my.pdf-tools.com/en/mypdftools/) and add/store it on the machine.
LIC_E_FEATURE error: The use of this function requires additional features activated in the license key
Some Pdftools products include optional features that require activation in the license key. If you receive this error, contact [Pdftools Sales](https://www.pdf-tools.com/contact/) to request the feature.
SSL certificate problem: unable to get local issuer certificate
Older systems may not trust the Amazon root certificate **Amazon Root CA 1**, potentially causing issues. Follow these steps to resolve them:
1. Download the root certificate [Amazon Root CA 1](https://www.amazontrust.com/repository/AmazonRootCA1.pem) from the Amazon website.
2. Add it to your system's trusted root certificate store.
---
## Pdftools Licensing Service
import DocCardList from '@theme/DocCardList';
import useBaseUrl from '@docusaurus/useBaseUrl';
Learn about the available configuration options for managing the Pdftools license keys. This page provides a basic overview of the licensing system and links to relevant documents that guide you through installation and configuration.
A valid license key is necessary to use the Pdftools products. A cloud-based **Pdftools Licensing Service (PLS)** manages the license key validation. You can also use a **Licensing Gateway Service (LGS)** that sends the validation data to the PLS. An internet connection is necessary to validate the license keys in the LGS default configuration. You can configure offline license key validation, where the license keys stay valid without an internet connection for various periods of time.
:::info
The PLS is available for:
- Pdftools SDK
- Conversion Service (version 4.7+)
:::
## LGS supported operating systems and environments
The Licensing Gateway Service (LGS) is available for multiple operating systems:
| Operating system | Package | Supported architecture | Tested |
|-------------------------------------------------|---------|------------------------|------------------------------------------------------------|
| Windows 8+ | MSI | x64 | Windows 8, 8.1, 10, 11 |
| Linux | Snap | x64 | Ubuntu 22.04+, Debian 12+, Fedora 38+, openSUSE Leap 15.5+ |
| Other Linux distribution (glibc 2.34+ and Snap) | Snap | x64 | |
:::note Use MSI instead of Snap on WSL
LGS isn't supported on Windows Subsystem for Linux (WSL). Use the native Windows MSI package instead of Snap on WSL.
:::
## LGS system requiremetns
| **Requirement** | **Docker Container** | **Windows** | **Linux** |
|-------------------|------------------------------|-----------------------|--------------------------------|
| **CPU** | 1 vCPU | 64-bit processor with SLAT support | 64-bit processor with virtualization support |
| **Memory** | Minimum of 512 MB | Minimum of 4 GB (recommended 8 GB or more) | Minimum of 4 GB (recommended 8 GB or more) |
| **Disk space** | Approximately 300 MB or more | At least 10 GB of free disk space | At least 10 GB of free disk space |
## License validation modes
You can set up the Pdftools products in several ways to validate the license keys. The LGS is an intermediary between your local installations of Pdftools products and the Pdftools Licensing Server (PLS). The LGS can borrow license keys for products installed in your network. As a result, machines with Pdftools products don't require an internet connection to validate their license keys.
On this page, you can learn about:
- The default configuration. Review [Direct connection to the PLS](#direct-connection-to-the-pls) section.
- How to enable a partially offline license key validation using the connected mode. Review [Partial or full offline license key validation](#partial-or-full-offline-license-key-validation) section.
- How to enable fully offline license key validation. Review [Partial or full offline license key validation](#partial-or-full-offline-license-key-validation) section.
### Direct connection to the PLS
In the default configuration, the Pdftools software validates the license keys directly with the PLS. This setup requires a continuous internet connection. Any network outages may disrupt system operations and limit access and usability of the Pdftools products due to connectivity issues.
### Partial or full offline license key validation
You can configure the LGS to validate the license keys offline for varied periods of time.
- **Connected mode (partially offline configuration)**: Validate the license keys for one or many installations of the Pdftools products in your local network. Your local network can stay without an internet connection, and the license keys are validated from one computer, which serves as the gateway. This computer is the only machine in your network that needs to be online to send the usage data. The computer with the gateway can also stay offline for varied amounts of time.
- **Full offline mode**: Stay fully offline with valid license keys for at least three months or more, depending on the type of your license. This option has the same benefits as the **connected mode** and lets the computer with the LGS stay fully offline.
1. Download the LicensingGatewayService.msi package.
1. Run the installer.
The installer also creates a Windows service that acts as an agent to regularly synchronize the LGS with the Pdftools Licensing Server.
:::info Prerequisite
On Linux systems, the LGS requires **glibc 2.34+**.
:::
1. Download the licgwy_amd64.snap package.
1. Run the installer with the following command:
```bash
snap install licgwy_amd64.snap --classic --dangerous
```
The installer also creates a service that acts as an agent to regularly synchronize the LGS with the Pdftools Licensing Server.
## Configure the LGS
To configure the LGS:
1. Locate the LGS configuration file `appsettings.json`:
For Windows, the file is in the installation folder, for example:
```
C:\Program Files\Pdftools\Licensing Gateway Service\appsettings.json
```
For Linux systems the file is in the `$SNAP_DATA` directory, for example:
```
/var/snap/licgwy/current/appsettings.json
```
Example configuration file:
```json
{
"LicensingServicePortNumber": 9999,
"LogFilePath": "C:/logs/pdftls/log.txt",
"LogRetentionDays": 7
}
```
1. You can configure these options:
- **Licensing Service Port number**: Set the port number used by the service. The default value is `9999`.
- **Log file path**: Specify the desired path of the log files.
- **Log retention**: Define the number of days the log files are kept.
1. Restart the service after modifying the `appsettings.json` file for the changes to take effect.
1. To ensure that the LGS can always connect to the Pdftools Licensing Server, add the service to the allowlist of any configured firewall.
:::caution
If the machine with the LGS becomes inaccessible, you can borrow a license key on another machine without returning it first.
If you try to borrow the license key more than once in this situation, **the license key is blocked**.
You cannot use or return the blocked license key on any other machine. To reset the license key, contact Pdftools support. Review the [Support](/docs/support) page.
:::
## Use the CLI utility
The LGS includes a command-line interface utility designed to manage and borrow license keys associated with your Pdftools products.
:::note
When you activate a license key in the LGS, it is linked to the machine where you activated it. If you install LGS on another machine, deactivate the license key so you can activate it again in the LGS.
:::
### Borrow a license
Borrowing means adding license keys to the LGS to validate them for the machines in your local network automatically. To borrow a license, use the following command and include the license key:
```shell
licgwy add LICENSE_KEY_VALUE
```
Replace `LICENSE_KEY_VALUE` with your license key.
:::info
When you run this command, a connection is opened between the LGS and the Pdftools Licensing Server to validate the license key for a period of time. The LGS lets you use multiple license keys at the same time.
:::
:::caution
Use a license key only on **one machine or one proxy service**.
If you want to reuse a license key installed on another machine, return the license key first before adding it to the new machine. Review [Return a license](#return-a-license) for more information.
:::
### Check licenses and the service status
To view all license keys added to the system, use the following command:
```shell
licgwy list
```
To view the connection status between the LGS and the Pdftools Licensing Service, use the following command:
```shell
licgwy status
```
### Synchronize licenses
To establish an active connection between the LGS and the Pdftools Licensing Server manually, use the command:
```shell
licgwy sync
```
This command contacts the Pdftools Licensing Server and synchronizes usage using the cached data stored by the LGS.
### Return a license
To return a borrowed license, use the `remove` command.
You must perform the step to return the license to the Pdftools Licensing Server before it can be added to another machine.
```shell
licgwy remove LICENSE_KEY_VALUE
```
Replace `LICENSE_KEY_VALUE` with your license key.
:::caution
A license remains borrowed by a specific machine until it is returned, even if it becomes deactivated.
Return the license before another machine can borrow it.
:::
To return all license keys added to the LGS, use the command:
```shell
licgwy remove-all
```
### LGS CLI commands
To access a full list of available commands, use the ` licgwy help` command.
| Command | Description |
| --------------------------------------------- | ------------------------------------------------------------------------------ |
| `licgwy help` | Get instructions on how to use the CLI with a full list of commands. |
| `licgwy version` | Get the LGS version number. |
| `licgwy add LICENSE_KEY_VALUE` | Add a new license key |
| `licgwy remove LICENSE_KEY_VALUE` | Remove a license key |
| `licgwy remove-all` | Remove all license keys |
| `licgwy status` | Check the licensing service status. |
| `licgwy list` | Get information about added license keys and for how long they are valid. |
| `licgwy sync` | Connect to Pdftools Licensing Server on demand (refreshes the time on all borrowed licenses) |
## Connected mode with Pdftools OCR Service
If you configured the connected mode with the Pdftools OCR Service, update your worker nodes configuration. Follow the steps described in [Configuration in connected mode and full offline mode](../products/ocr-service-license.mdx#configuration-in-connected-mode-and-full-offline-mode) section.
---
## Full offline mode
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
import useBaseUrl from '@docusaurus/useBaseUrl';
Use the Pdftools software fully offline with valid license keys for at least three months or more, depending on your license. Your local network can stay without an internet connection, and license keys are validated for a set period of time.
:::note Limitations of full offline mode
The full offline mode **isn't** available in the following cases:
- For the free trial license keys created in the [Pdftools Portal](https://portal.pdf-tools.com/).
- To Docker users. If you are using the Pdftools SDK or the Conversion Service within a Docker container, you can use:
- The default license consumption reporting. For more details, review [Direct connection to the PLS](./README.mdx#direct-connection-to-the-pls).
- A connected mode that can be described as a partially offline mode. For more information, review [Connected mode](./licensing-service.mdx) .
- A containerized mode designed for Docker containers. For more information, review [Containerized mode](./docker-licensing-service.mdx).
:::
## Before you start
Ensure your license key supports the full offline mode. Whether you can enable the offline mode depends on the order form and quote you accepted from Pdftools. If you require an upgrade to get this feature, reach out through the [Contact form](https://www.pdf-tools.com/contact/).
## Install the LGS
Install the LGS to enable fully offline configuration. Download and install the package on a machine in your network that is **not** connected to the internet.
:::caution LGS is installed with the Conversion Service on Windows Server
- The Conversion Service comes with the LGS preinstalled on Windows. Installing the LGS on such a machine for the second time may render the Conversion Service unusable. For more details, review the implementation of the [Licensing Gateway Service](../products/conversion-service-license.mdx#licensing-gateway-service) in the Conversion Service licensing documentation. Skip to [Configure the LGS for offline use](#configure-the-lgs-for-offline-use) if you installed the Conversion Service on a Windows Server machine.
- The full offline mode is available in the Conversion Service version 6+, not in the previous versions. Configure the full offline mode using steps described in [Full offline mode license activation](../products/conversion-service-license.mdx#full-offline-mode-license-activation) section.
:::
:::note
Ensure you install the LGS on an offline machine in full offline mode.
However, in the connected mode, you need to install the LGS on a computer that is connected to the internet.
:::
1. Download the LicensingGatewayService.msi package.
1. Run the installer.
The installer also creates a Windows service that acts as an agent to regularly synchronize the LGS with the Pdftools Licensing Server.
:::info Prerequisite
On Linux systems, the LGS requires **glibc 2.34+**.
:::
1. Download the licgwy_amd64.snap package.
1. Run the installer with the following command:
```bash
snap install licgwy_amd64.snap --classic --dangerous
```
The installer also creates a service that acts as an agent to regularly synchronize the LGS with the Pdftools Licensing Server.
## Configure the LGS for offline use
To configure the LGS:
1. Locate the LGS configuration file `appsettings.json`:
For Windows, the configuration file is in the installation folder, for example:
```
C:\Program Files\Pdftools\Licensing Gateway Service\appsettings.json
```
For Linux systems the configuration file is in the `$SNAP_DATA` directory, for example:
```
/var/snap/licgwy/current/appsettings.json
```
Example configuration file:
```json
{
"LicensingServicePortNumber": 9999,
"LogFilePath": "C:/logs/pdftls/log.txt",
"LogRetentionDays": 7
}
```
1. Enable offline mode in LGS. Update the configuration file so that the `IsOfflineMode` property is set to `true`.
Example configuration file after update:
```json
{
"LicensingServicePortNumber": 9999,
"LogFilePath": "C:/logs/pdftls/log.txt",
"LogRetentionDays": 7,
"IsOfflineMode": true
}
```
1. Optionally, you can configure these options:
- **Licensing Service Port number**: Set the port number used by the service. The default value is `9999`.
- **Log file path**: Specify the desired path of the log files.
- **Log retention**: Define the number of days the log files remain.
1. Restart the service after modifying the `appsettings.json` file so the changes take effect.
## Install the Licensing Gateway Activator
Download and install the Licensing Gateway Activator (LGA) on a machine in your network that is **connected to the internet**.
1. Download the LicensingGatewayActivator.msi package.
1. Run the installer.
1. Download the licgwyactivator_amd64.snap package.
1. Run the installer with the following command:
```bash
snap install licgwyactivator_amd64.snap --classic --dangerous
```
## Offline license configuration
The following sections explain how to manage your license keys offline using the LGS CLI and LGA CLI tools or online using a combination of the LGS CLI and Pdftools Portal.
You can activate your license in the full offline mode by following the procedures in the following sections:
- [Activate license key in the Pdftools Portal](#activate-license-key-in-the-pdftools-portal)
- [Activate license key using the Licensing Gateway Activator CLI](#activate-license-key-using-the-licensing-gateway-activator-cli)
You can deactivate your license in the full offline mode by following the procedures in the following sections:
- [Deactivate license key in the Pdftools Portal](#deactivate-license-key-in-the-pdftools-portal)
- [Deactivate license key using the Licensing Gateway Activator CLI](#deactivate-license-key-using-the-licensing-gateway-activator-cli)
### Prerequisites
To use the license keys offline, fulfill the following prerequisites:
- The **Licensing Gateway Service CLI** (`licgwy`) is installed on a machine that is **not** connected to the internet (**offline machine**).
- Optional: The **Licensing Gateway Activator CLI** (`licgwyactivator`) is installed on the machine that **is** connected to the internet (**online machine**). This is only necessary in the procedures that involve license key activation and deactivation using the **Licensing Gateway Activator CLI**.
### License key activation
#### Activate license key in the Pdftools Portal
Activate your license key in the full offline mode in the Pdftools Portal by following these steps:
1. On the offline machine with the installed **Licensing Gateway Service**, run the following command to generate an offline activation token:
```bash
licgwy export-activation "LICENSE_KEY_VALUE"
```
- Replace `LICENSE_KEY_VALUE` with your license key.
1. Copy the generated **offline activation token**.
1. Log in to the [Pdftools Portal](https://portal.pdf-tools.com/).
1. Go to [Licenses](https://portal.pdf-tools.com/licenses) tab.
1. Paste the **offline activation token** into the field marked as **Insert your token here...**.
1. Click **Activate**, and then click **Continue**.
1. Copy the generated **license activation token**.
1. On the offline machine, run the following command to activate or extend the license key:
```bash
licgwy import-activation "LICENSE_ACTIVATION_TOKEN"
```
- Replace `LICENSE_ACTIVATION_TOKEN` with your license activation token from the previous step.
The license is now activated or extended and ready for use.
:::note
When you activate a license key in the LGS, it is linked to the machine where you activated it. If you install LGS on another machine, deactivate the license key so you can activate it again in the LGS.
:::
#### Activate license key using the Licensing Gateway Activator CLI
Activate your license key in the full offline mode using the Licensing Gateway Activator CLI by following these steps:
1. On the offline machine with the installed **Licensing Gateway Service**, run the following command:
```bash
licgwy export-activation "LICENSE_KEY_VALUE"
```
- Replace `LICENSE_KEY_VALUE` with your license key.
1. Copy the generated **offline activation token**.
1. On the online machine with the installed **Licensing Gateway Activator**, run the following command:
```bash
licgwyactivator activate "OFFLINE_ACTIVATION_TOKEN"
```
- Replace `OFFLINE_ACTIVATION_TOKEN` with the offline activation token from the previous step.
1. Copy the generated **license activation token**.
1. On the offline machine, run the following command to activate or extend the license key:
```bash
licgwy import-activation "LICENSE_ACTIVATION_TOKEN"
```
- Replace `LICENSE_ACTIVATION_TOKEN` with your license activation token from the previous step.
The license is now activated or extended and ready for use.
:::note
When you activate a license key in the LGS, it is linked to the machine where you activated it. If you install LGS on another machine, deactivate the license key so you can activate it again in the LGS.
:::
### License key deactivation
**Why deactivate a license key?** If a machine with a license key activated in an LGS becomes inaccessible, the license key will be blocked and unusable. Unfortunately, you won't be able to activate or deactivate the blocked license key and move it to another machine. This often happens with discontinued servers or removed virtual machines where our customers did not deactivate their license key in LGS before removing the machine itself.
:::info
If your license key became blocked, contact Pdftools support to unblock the license key. Review the [Support](/docs/support) page.
:::
If you want to remove a machine where you have activated license keys in LGS:
1. Deactivate the license key.
1. Remove the machine.
1. Activate the license key on another machine with LGS.
#### Deactivate license key in the Pdftools Portal
Deactivate your license key in the full offline mode in the Pdftools Portal by following these steps:
1. On the offline machine with the installed **LGS**, run the following command to locally deactivate the license key:
```bash
licgwy export-deactivation "LICENSE_KEY_VALUE"
```
- Replace `LICENSE_KEY_VALUE` with your license key.
- You cannot generate a new activation request token for the same license key until you complete all deactivation steps.
1. Copy the generated **license deactivation request token**.
1. Log in to [Pdftools Portal](https://portal.pdf-tools.com/).
1. Go to the [Licenses](https://portal.pdf-tools.com/licenses) tab.
1. Click **Deactivate**.
1. Paste the **license deactivation request token** into the field marked as **Insert your token here...**.
1. Click **Deactivate**, and then click **Continue**.
1. Copy the generated **license deactivation token**.
1. On the offline machine, run the following command to deactivate the license key:
```bash
licgwy import-deactivation "LICENSE_DEACTIVATION_TOKEN"
```
- Replace `LICENSE_DEACTIVATION_TOKEN` with your license deactivation token from the previous step.
The license has now been completely removed from the system. If necessary, you can generate a new activation request token for this license key.
#### Deactivate license key using the Licensing Gateway Activator CLI
Deactivate your license key in the full offline mode using the Licensing Gateway Activator CLI by following these steps:
1. On the offline machine with the installed **LGS**, run the following command to locally deactivate the license key:
```bash
licgwy export-deactivation "LICENSE_KEY_VALUE"
```
- Replace `LICENSE_KEY_VALUE` with your license key.
- You cannot generate a new activation request token for the same license key until you complete all deactivation steps.
1. Copy the generated **license deactivation request token**.
1. On the online machine with the installed **Licensing Gateway Activator**, run the following command:
```bash
licgwyactivator deactivate "OFFLINE_DEACTIVATION_TOKEN"
```
- Replace `OFFLINE_DEACTIVATION_TOKEN` with the token from the previous step.
1. Copy the generated **license deactivation token**.
1. On the offline machine, run the following command to deactivate the license key:
```bash
licgwy import-deactivation "LICENSE_DEACTIVATION_TOKEN"
```
- Replace `LICENSE_DEACTIVATION_TOKEN` with your license deactivation token from the previous step.
The license has now been completely removed from the system. If necessary, you can generate a new activation request token for this license key.
## References
The following sections list the most important LGS and Licensing Gateway Activator commands in the fully offline configuration.
### LGS CLI commands
The LGS includes a command-line interface (CLI) utility for managing licenses associated with your Pdftools products.
To access a full list of available commands, use the `licgwy help` command.
| Command | Description |
|---------------------------------------------------------|---------------------------------------------------------------------------|
| `licgwy help` | Get instructions on how to use the CLI with a full list of commands. |
| `licgwy version` | Get the LGS version number. |
| `licgwy export-activation LICENSE_KEY_VALUE` | Export an activation request. |
| `licgwy import-activation LICENSE_ACTIVATION_TOKEN` | Import an activation response. |
| `licgwy export-deactivation LICENSE_KEY_VALUE` | Export a deactivation request. |
| `licgwy import-deactivation LICENSE_DEACTIVATION_TOKEN` | Import a deactivation response. |
| `licgwy status` | Check the licensing service status. |
| `licgwy list` | Get information about added license keys and for how long they are valid. |
### Licensing Gateway Activator CLI commands
The Licensing Gateway Activator is a command-line interface that you can use to get activation or deactivation tokens for your offline license keys.
To access a full list of available commands, use the `licgwy help` command.
| Command | Description |
|----------------------------------------------------|----------------------------------------------------------------------|
| `licgwyactivator help` | Get instructions on how to use the CLI with a full list of commands. |
| `licgwyactivator version` | Get the licensing gateway activator version number. |
| `licgwyactivator activate LICENSE_REQUEST_TOKEN` | Activate an offline token. |
| `licgwyactivator deactivate LICENSE_REQUEST_TOKEN` | Deactivate an offline token. |
## Full offline mode with Pdftools OCR Service
If you configured the full offline mode with the Pdftools OCR Service, update your worker nodes configuration. Follow the steps described in [Configuration in connected mode and full offline mode](../products/ocr-service-license.mdx#configuration-in-connected-mode-and-full-offline-mode) section.
---
## Configure SSL
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
Learn how to configure the Pdftools Licensing Gateway Service (LGS) to use the SSL and create HTTPS communication for your license key validation.
:::info
Before configuring SSL with the LGS, review [Configure the LGS](licensing-service.mdx#configure-the-lgs) section.
:::
## SSL configuration
To enable SSL compatibility with LGS, follow these steps depending on your operating system:
1. Find the `appsettings.json` LGS configuration file. It is located in the installation folder. For example:
```
C:\Program Files\Pdftools\Licensing Gateway Service\appsettings.json
```
2. Add the following keys to your configuration file.
- Specify the port where SSL communication occurs:
```
LicensingServiceHTTPSPortNumber: 9990
```
- Add path to the certificate file:
```
CertPemFile: C:/certs/certificate.pem
```
- Add path to the private key file:
```
CertKeyFile: C:/certs/privatekey.key
```
:::warning
Include all files and configuration keys mentioned above. If you miss any of them the LGS doesn't activate SSL and defaults to HTTP communication.
:::
3. Example configuration file:
```json
{
"LicensingServicePortNumber": 9999,
"LogFilePath": "C:/logs/pdftls/log.txt",
"LogRetentionDays": 7,
"IsOfflineMode": false,
"LicensingServiceHTTPSPortNumber": 9990,
"CertPemFile": "C:/certs/cert.pem",
"CertKeyFile": "C:/certs/private-key.key"
}
```
4. Restart service after changing configuration by running the following command:
```powershell
Stop-Service -Name "Licensing Gateway Service"
Start-Service -Name "Licensing Gateway Service"
```
1. Find the `appsettings.json` LGS configuration file. It is located in the `$SNAP_DATA` directory. For example:
```
/var/snap/licgwy/current/appsettings.json
```
2. Add the following keys to your configuration file.
- Specify the port where SSL communication occurs:
```
LicensingServiceHTTPSPortNumber: 9990
```
- Add path to the certificate file:
```
CertPemFile: C:/certs/certificate.pem
```
- Add path to the private key file:
```
CertKeyFile: C:/certs/privatekey.key
```
:::warning
Include all files and configuration keys mentioned above. If you miss any of them the LGS doesn't activate SSL and defaults to HTTP communication.
:::
3. Example configuration file:
```json
{
"LicensingServicePortNumber": 9999,
"LogFilePath": "/usr/share/Pdftools/lgs/logs/log.txt",
"LogRetentionDays": 7,
"IsOfflineMode": false,
"LicensingServiceHTTPSPortNumber": 9990,
"CertPemFile": "/etc/lgs/ssl/cert.pem",
"CertKeyFile": "/etc/lgs/ssl/private-key.key"
}
```
4. Restart service after changing configuration by running the following command:
```bash
sudo snap restart licgwy
```
1. Add the following keys to your configuration file.
- Specify the port where SSL communication occurs:
```
LicensingServiceHTTPSPortNumber: 9990
```
- Add path to the certificate file:
```
CertPemFile: C:/certs/certificate.pem
```
- Add path to the private key file:
```
CertKeyFile: C:/certs/privatekey.key
```
:::warning
Include all files and configuration keys mentioned above. If you miss any of them the LGS doesn't activate SSL and defaults to HTTP communication.
:::
2. Example of the complete run command:
```bash
docker run --name lgsdocker \
-e LICENSE_KEYS="YOUR_LICENSE_KEY" \
-e LicensingServicePortNumber=9999 \
-e LicensingServiceHTTPSPortNumber=9990 \
-e CertPemFile=/etc/lgs/ssl/cert.pem \
-e CertKeyFile=/etc/lgs/ssl/private-key.pem \
-v /etc/lgs/ssl/:/etc/lgs/ssl/ \
-p 9999:9999 \
-p 9990:9990 \
-d \
pdftoolsag/license-gateway:latest
```
- Replace `YOUR_LICENSE_KEY` with the value of your license key.
- Ensure that you certificates are reachable by storing them at `/etc/lgs/ssl/` in your host system. You can alternatively replace and customise all port numbers, values, and file paths, but ensure to edit the previous command example accordingly.
If your configuration is correct, the LGS logs include information similar to:
```
[Information] Now listening on: "https://[::]:9990"
```
---
## 3-Heights SDK product licensing
# 3-Heights SDK licensing
Licenses for 3-Heights SDK products are managed using the License Manager. For more licensing related information, see the [Technical Note: License keys](https://www.pdf-tools.com/public/downloads/manuals/TechNoteLicenseKeys3Heights.pdf).
---
## Conversion Service licensing
import Copy from '/img/copy.svg';
import ArrowsRotate from '/img/arrows-rotate.svg';
import useBaseUrl from '@docusaurus/useBaseUrl';
Learn how to activate and configure license keys for the Conversion Service.
This page includes details about one of the Pdftools products. For a general overview of different licenses of Pdftools products, see [Licenses of Pdftools products](../README.mdx).
import Copy from '/img/copy.svg';
import useBaseUrl from '@docusaurus/useBaseUrl';
## Get trial license
To try or fully use the Conversion Service, you must obtain a license key. To get the Conversion Service evaluation license key for free, follow these steps:
1. [Sign up](https://portal.pdf-tools.com/account/sign-up) or log in to the [Pdftools Portal](https://portal.pdf-tools.com/).
1. On the **Products** page, next to the Conversion Service, click **Get started** or **See product**.
1. Next to the **Conversion Service Trial**, click the **Copy
Unable to add license key / License key could not be removed
To add and remove a page-based license key, the License Gateway requires an internet connection.
Activation Failed / License key could not be deactivated
**Usage-based licensing**: When you activate a license key in the LGS, it is linked to the machine where you activated it. If you install LGS on another machine, deactivate the license key so you can activate it again in the LGS. For more information, review [License key deactivation](../configure/offline-licensing-service.mdx#license-key-deactivation).
**Core-based licenses**: Most core-based licenses must be activated before they can be used and deactivated before they can be removed.
The activation and deactivation process requires an internet connection. If your system is running offline, review the [Offline usage](https://www.pdf-tools.com/public/downloads/manuals/TechNoteLicenseKeys.pdf#page=13) documentation.
### License validation or consumption errors
Some of the warnings and errors that can be encountered during regular use of the service.
License consumption failed (InvalidConfiguration)
There was an error in the consumption of the license page credits. There are several possible reasons for such an error.
Use the Conversion Service Configurator to view the current license status and if there are any errors.
Service not available due to a license issue
The validation of the current license failed. Please use the Conversion Service Configurator to view the current license status.
---
## Pdftools OCR Service licensing
By default, the [Pdftools OCR Service](/docs/ocr-service/) requires a network connection to validate the license key with the [Pdftools Licensing Service](../configure/README.mdx). Or, you can configure the Pdftools OCR Service to run without a network connection. For more information, see [Configure offline license key validation](#configure-offline-license-key-validation).
## Configure offline license key validation
If you need the Pdftools OCR Service to operate without a direct internet connection to verify the license key, set up the [Licensing Gateway Service](/docs/licenses/configure/licensing-gateway-service/) (LGS).
With the LGS, you can configure the Pdftools OCR Service to:
- Use a partially offline mode called **connected mode**. For more information, review [Connected mode](../configure/licensing-service.mdx).
- Use **full offline mode**. For more information, review [Full offline mode](../configure/offline-licensing-service.mdx).
### Configuration in connected mode and full offline mode
#### Prerequisites
To let the Pdftools OCR Service operate without a continuous internet connection, install and configure the LGS. Review [Connected mode](../configure/licensing-service.mdx), or [Full offline mode](../configure/offline-licensing-service.mdx) for specific guidance.
#### Procedure
After configuring the LGS with the Pdftools OCR Service using the connected mode or full offline mode, follow these steps:
1. Find your worker node's `appsettings.json`. The following is the default path of the worker configuration file:
```
C:\Program Files\Pdftools\Pdftools OCR Service\PdftoolsOcrWorker\appsettings.json
```
1. Edit the `LgsURL` parameter value to point to the machine where you configured the LGS. The default value is:
```
"LgsURL": "http://localhost:9999"
```
For more information, review [Default appsettings.json](/docs/ocr-service/guides/monitor/#default-appsettingsjson-1) in the Pdftools OCR Service documentation.
---
## PDF Toolbox SDK licensing
License for this product is managed using the License Manager. For more licensing related information, see the [Technical Note: License Keys](https://www.pdf-tools.com/public/downloads/manuals/TechNoteLicenseKeys.pdf).
Set the license key by using the `Sdk.Initialize` method before calling the library.
Contact the Pdftools sales team through the [Contact page](https://www.pdf-tools.com/contact/) to get an evaluation or full license key for the PDF Toolbox SDK. The evaluation license key is necessary to try the PDF Toolbox SDK.
---
## Pdftools SDK license management
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import Copy from '/img/copy.svg';
Learn how to manage the Pdftools SDK license keys. The information on this page applies to legacy and page-based licenses. The Pdftools SDK also includes the Toolbox add-on that can be used with the same license key.
## Request trial or full license
You can use the Pdftools SDK and the SDK Shell Tool without a license key with watermarked results. To get a full license and remove the watermarks, or to evaluate the Toolbox add-on:
1. Reach out to the sales team through the [Contact page](https://www.pdf-tools.com/contact/) and mark the Pdftools SDK as the product of your interest for a trial license.
## Find the license key
To find and copy a license key:
1. [Sign up](https://portal.pdf-tools.com/account/sign-up) or log in to the [Pdftools Portal](https://portal.pdf-tools.com/).
1. On the **Products** page, next to the Pdftools SDK, click **Get started** or **See product**.
1. Find your license key in the **License keys** section, and then click **Copy
```csharp
static void Main(string[] args)
{
try
{
// Set the URL to the Licensing Gateway Service.
Sdk.LicensingService = new Uri("http://my.gateway.com:9999");
// Set and check license key. If the license key is not valid, an exception is thrown.
Sdk.Initialize("$LicenseKey$");
```
```java
public static void main(String[] args)
{
try
{
// Set the URL to the Licensing Gateway Service.
Sdk.setLicensingService(new java.net.URI("http://my.gateway.com:9999"));
// Set and check license key. If the license key is not valid, an exception is thrown.
Sdk.initialize("$LicenseKey$");
```
:::note
More information about the `LicensingService` property is available in the SDK documentation for [.NET](https://api-reference.pdf-tools.com/pdfsdk/1.3/dotnet/html/P_PdfTools_Sdk_LicensingService.htm) and [Java](https://api-reference.pdf-tools.com/pdfsdk/1.3/javadoc/com/pdftools/Sdk.html#setLicensingService(java.net.URI)).
:::
## Check the license status
When the Pdftools SDK is successfully initialized, check your license status by accessing the `LicenseInfoSnapshot` property of the `SDK` class. This property provides the following information about the current license:
- `IsValid`: License validity.
- `ExpirationDate`: The date and time when the license expires.
- `RemainingPages`: The number of pages available to be processed, based on the license agreement.
- `Overconsumption`: The number of pages available to be processed, before the SDK stops functioning.
If the `RemainingPages` value reaches zero, the Pdftools SDK provides a limited number of `Overconsumption` pages. The `Overconsumption` pages give you time to update your license agreement without disrupting your business processes.
:::caution
If both the `RemainingPages` and `Overconsumption` values reach zero, the Pdftools SDK stops functioning until the licensing service is updated with new license information.
:::
:::note
More information about the `LicenseInfoSnapshot` property is available in the SDK documentation for [.NET](https://api-reference.pdf-tools.com/pdfsdk/latest/dotnet/html/P_PdfTools_Sdk_LicenseInfoSnapshot.htm) and [Java](https://api-reference.pdf-tools.com/pdfsdk/latest/javadoc/com/pdftools/Sdk.html#getLicenseInfoSnapshot()).
:::
## Configure proxy
Configure proxy settings when you need all your HTTPS and HTTP communication to go through one central point in your network. If your implementation of the Pdftools SDK requires connectivity to services external to your network that are not directly reachable by your application (for example, time-stamp authority (TSA), or you are using page credit-based license key with configured LGS), or the SDK is operating in an environment where direct internet access is restricted, such as behind a firewall.
**Configure proxy if**:
- You have a central point in your network through which you wire all your HTTPS and HTTP communication.
- If you have a page credit-based license key and a central point in your network through which you wire all your HTTPS and HTTP communication.
| **Condition** | **Proxy Required?** | **Notes** |
| ------------------------------------------------------------------------------------- | ------------------- | ------------------------------------------------------------------ |
| All HTTPS/HTTP communication must go through a central network point | Yes | General requirement when routing traffic through a proxy. |
| SDK must connect to external services not directly reachable (for example, TSA, LGS) | Yes | Includes scenarios behind firewalls or restrictive environments. |
| Page credit-based license key **and** centralized HTTPS/HTTP routing | Yes | LGS or credit license usage behind a proxy requires configuration. |
| Trial license key in use | No | Proxy isn't required even if centralized routing exists. |
| Page credit-based license key **without** the need for centralized HTTPS/HTTP routing | No | Proxy isn't required if the app can directly access the internet. |
For specific steps to enable the proxy server, review the following resources depending on your use case:
- Digital signing proxy configuration, review [Using a proxy server](/docs/pdf-tools-sdk/sign-and-secure/sign/configure-digital-signing/#using-a-proxy-server).
- For other use cases, review the following [Procedure](#procedure).
### Procedure
To configure a proxy, assign the `PdfTools.Sdk` class a `Proxy` server URI that the SDK will use for all HTTP and HTTPS communications with remote services. Follow these steps to configure a proxy:
1. In your application code, set the proxy before initializing the SDK:
http[s]://[USER[:PASSWORD]@]HOST[:PORT]
Where:
- `http`/`https`: Protocol for connection to proxy.
- `USER:PASSWORD` (optional): Credentials for connection to proxy (basic authorization).
- `HOST`: Hostname of proxy.
- `PORT`: Port for connection to proxy.
For example, in C#:
```csharp
Sdk.Proxy = new Uri("https://myuser:mypassword@proxy.example.com:8080");
```
1. **After** setting the proxy configuration, initialize the SDK using your license key. It is important to call the initialization **after** the proxy configuration. For more information about the Pdftools SDK initialization, review [Activate the Pdftools SDK license](#activate-the-pdftools-sdk-license).
In the Pdftools SDK Shell Tool, you can configure the proxy using the -proxy URL option. In this option, replace the `URL` with your actual proxy URL.
:::note Notes
- You can also find information about the proxy configuration in the API references, for example [Sdk.Proxy Property](https://api-reference.pdf-tools.com/pdfsdk/latest/dotnet/html/P_PdfTools_Sdk_Proxy.htm?utm_source=chatgpt.com) in the .NET API documentation.
- Toolbox add-on currently doesn't support proxy configuration.
:::
---
## PDF Viewer SDK licensing
The PDF Viewer SDK differs in how you can use the license keys and initialize the SDK. Review [version 5](#version-5) and [version 4](#version-4) sections separately depending on which version you use.
## Version 5
### License overview
The following table explains the pricing and feature offering available for various license types of the PDF Viewer SDK:
No license
Free view-only
Trial
Professional
Business
Enterprise
How to
No license key is need
Contact sales
Contact sales
Contact sales
Contact sales
Contact sales
Watermark
Yes
No
No
No
No
No
Feature sets
View-only
View-only
All
Select one
Select three
All
Domains
-
One
On demand
One
Three
On demand
Maximum concurrent users
100
100 extensible
100 extensible
100 extensible
1,000 extensible
Contract based
### License key
The PDF Viewer SDK displays watermarked pages by default. Use a license key to remove the watermark for free. For more details, review [Manage license key](/docs/pdf-web-viewer/getting-started/#manage-license-key) section.
## Version 4
Without an active license the PDF Viewer SDK version 4 applies a watermark to the viewed PDFs. Try the PDF Viewer SDK for free. See the [product demo](https://www.pdf-tools.com/pdfwebviewer/) in action. Install PDF Viewer SDK locally from the [npmjs](https://www.npmjs.com/package/@pdf-tools/four-heights-pdf-web-viewer) website. Get in touch with the Pdftools sales team through the [Contact page](https://www.pdf-tools.com/contact/) to get a full license and remove the watermark.
Review how to enter the license key in the [Basic usage](/docs/pdf-web-viewer/4/getting-started/#basic-usage) documentation.
### Troubleshooting
The following sections can help you to fix specific issues related to the PDF Viewer SDK licensing.
#### License key cannot be set
If the license key cannot be set, the call to the `PdfWebViewer` constructor results in an error.
##### Possible causes
- There is a typographic error in the license key.
- When the key was copied, the operation altered the characters in the key, such as commas.
- The key has a wrong format.
- The key belongs to a different product.
- The key is an evaluation license key that expired.
##### Solution
Make sure the key is issued for the PDF Viewer and has the following format:
```
<4H,V4,VIEWWEB,XXXXXXXXXXXXXXXXXXXX>
```
If an evaluation license key has expired and you want to extend the period of evaluation, use the [Contact page](https://www.pdf-tools.com/contact/) to request a new evaluation license key.
#### License check fails at runtime
In this case, the license can be set and the call to the constructor `PdfWebViewer` is successful. However, when opening a PDF file, you are prompted with message: "The current license does not permit running the product on this domain."
##### Possible causes
- The license key is not meant to be used with the current domain.
##### Solution
Ensure that the domain on which the PDF Viewer is running matches the domain to which the license key is registered.
---
## Pdftools OCR Service
import useBaseUrl from '@docusaurus/useBaseUrl';
The OCR Service enables optical character recognition (OCR) to extract text from images and scanned documents, transforming them into searchable and editable PDF documents.
You can use the Pdftools OCR Service with the Conversion Service on Windows Server.
## Key features
- Embeds the recognized text in Unicode format into PDF or PDF/A files.
- Supports over 180 natural and technical languages.
- Provides an OCR service mode for shared use across multiple platforms.
- Predefined and custom OCR profiles to optimize for accuracy or performance.
- Automatic skew correction, rotation, and resolution handling.
- Detection of tables, barcodes, engineering drawings, and other complex layout elements.
## System architecture
The Pdftools OCR Service comprises two .NET Core applications, both running on Kestrel servers:
- **Manager node**: This node handles HTTP requests and dispatches jobs to available workers.
- **Worker node**: Performs the OCR processing. This node handles OCR processing and remains the most resource-intensive component.
This separation allows for flexible deployment and scaling, where a single manager can coordinate multiple workers. For more information, review [Scale the Pdftools OCR Service](./guides/scale.mdx).
## System requirements
### Worker nodes
These nodes run the OCR engine and require more processing power and memory. The worker node recommended hardware setup is:
- Windows 8 or newer (x64)
- 8 GB RAM or more
- Quad-core CPU or better
- SSD with at least 4 GB free space
### Manager nodes
These nodes coordinate OCR jobs and handle requests, with significantly lower system requirements. The manager node recommended hardware setup is:
- Windows 8 or newer (x64)
- 4 GB RAM
- Quad-core CPU
- SSD storage
### For standalone installations
You can also install the manager and the worker on the same machine. The requirements allocated for [Worker nodes](#worker-nodes) suffice.
## Licensing
The Pdftools OCR Service requires a license key to operate. You can use one of two license key types:
- Trial license key
- Full license key
For information about configuring license keys, review [Get started with OCR in the Conversion Service](./getting-started/README.mdx). For offline licensing options, review [Pdftools OCR Service licensing](/docs/licenses/products/ocr-service-license/).
---
---
## Get started with OCR in the Conversion Service
import useBaseUrl from '@docusaurus/useBaseUrl';
import Copy from '/img/copy.svg';
import DownloadNonPadded from '/img/download-nopadding.svg';
import PenIcon from '/img/pen-solid.svg';
Learn how to install and configure the Pdftools OCR Service with the Conversion Service.
## Install Pdftools OCR Service
To install the Pdftools OCR Service, follow these steps:
1. Log in to the [Pdftools Portal](https://portal.pdf-tools.com/).
1. Go to the **Products**, find the **Pdftools OCR Service**, and then click **Get started** or **See product**.
1. In the **Product kits** section, find the `PdftoolsOcrService-VERSION_NUMBER.msi` package, and then click **Download "` placeholder with your license key, and then save the file.
:::tip
In its default configuration, the Pdftools OCR Service requires a network connection to validate the license key. For information about partially offline or fully offline solution, review [Pdftools OCR Service licensing](/docs/licenses/products/ocr-service-license/).
:::
1. Open Windows start menu and search for **Services**, and then search for **Pdftools OCR Service Worker** and start the service.
1. Optional: Check whether the installation succeeded through log files. Example path to `worker-logYYYYMMDD.txt` file:
```
C:\ProgramData\Pdftools\OcrService\logs\worker-log20251007.txt
```
If you need to remove a trial license key or in general insert another key, repeat the procedure from step 7.
:::info Supported Platforms
The Pdftools OCR Service can be installed on Windows Server and Windows machines. Support for Docker and Linux is on our roadmap.
:::
## Set up Pdftools OCR Service with Conversion Service
Learn how to enable and configure the Pdftools OCR Service in the Conversion Service.
:::tip Before you start
- Install and configure the Conversion Service. For detailed instructions, review [Get started with the Conversion Service](/docs/conversion-service/getting-started/).
:::
### Enable Pdftools OCR Service in the Conversion Service
The following steps explain how to enable and configure OCR in the Conversion Service profile:
1. In the Conversion Service Configurator, go to **Workflows & Profiles**.
1. Click the pen icon ",
"LgsURL": "http://localhost:9999"
}
}
```
- `PortNumber`: Port used by the worker node for incoming requests, **7998** is the default in this case.
- `LogFilePath`: Path to the log file and the retention period for logs.
- `LogRetentionDays`: Retention period for logs.
- `FileStorage`
- `FileStorageType`: Storage system type (for example `HostFileSystem`).
- `FilesDirectoryPath`: Directory path for storing OCR-processed files.
- `ServiceCommunication`
- `ServiceCommunicationType`: Communication method that reaches the worker (currently `Rest`).
- `Licensing`
- `LicenseKey`: Your Pdftools product key. Provide the license key in every worker that you set up.
- `LgsURL`: Your connection URL to the [Licensing Gateway Service (LGS)](/docs/licenses/configure/). An optional property. If you **don't** specify the `LgsURL`, the Pdftools OCR Service automatically connects to the Pdftools Licensing Service, requiring an internet connection.
---
## Work with profiles
Pdftools OCR Service lets you fine-tune the OCR engine using various parameters. You can specify parameters for image preprocessing, analysis, recognition, and synthesis to obtain the optimal speed and quality of processing.
## Predefined profiles
The Pdftools OCR Service lets you set predefined profiles designed for the main usage scenarios (the specifications of all predefined profiles are described in [PredefinedProfiles](../references/parameters/README.mdx#predefinedprofile) references). The settings provided in these profiles are best suited for their respective situations. Often, a profile comes in two versions: one optimized for the highest quality of the resulting document and the other optimized for the fastest processing speed.
## Custom profiles
You can also create your own profile file. These profile files use INI file syntax. You can add comments in an INI file by starting a line with a semicolon (`;`).
The sections contain the names of the objects whose properties can be specified. The keys contain the properties with their values. The special section called `UserData` can contain any user-defined keys. The values of Boolean properties are represented by the strings `true` or `false`, while enumeration properties are represented by corresponding constants, for example:
```ini
[PrepareImageMode]
DiscardColorImage = true
[PDFExportParams]
TextExportMode = PEM_ImageOnText
; This line is a comment
[RecognizerParams]
FastMode = true
```
The [`Profile`](../references/parameters/README.mdx#profile) parameter lets you load a custom profile file. After this file is loaded, the created objects will have the new values specified in the file. Loading parameters from a profile is similar to specifying the corresponding properties in the code. If an empty string is passed to the `Profile` parameter, the standard default values will be used.
The objects in the square brackets (for example, `[RecognizerParams]`) represent INI file sections. You may include various parameters only under certain INI file sections. For more details, review [Custom profiles](../references/parameters/custom-profiles/README.mdx).
import PenIcon from '/img/pen-solid.svg';
import useBaseUrl from '@docusaurus/useBaseUrl';
To configure a custom profile for specific OCR processing behavior, follow these steps:
1. Create a custom profile INI file.
1. In the Conversion Service Configurator, go to **Workflows & Profiles**.
1. Click the pen icon "
}
}
```
In a default installation, the worker configuration file is located at:
```
C:\Program Files\Pdftools\Pdftools OCR Service\PdftoolsOcrWorker\appsettings.json
```
1. Share a common file storage between all manager and worker nodes:
```json
{
"FileStorage": {
"FileStorageType": "HostFileSystem",
"FilesDirectoryPath": "F:/SharedFolder/ProgramData/Pdftools/OcrService/Files"
}
}
```
- `FileStorage`
- `FileStorageType`: Storage system type (for example, `HostFileSystem`).
- `FilesDirectoryPath`: Directory path for storing OCR-processed files.
1. Make sure every **manager** and all **worker** nodes:
- Uses the same `FileStorage` settings.
- Has read and write permission for the shared directory.
## Scaling manager nodes
You can scale the manager nodes similarly to the worker nodes.
:::info
Switch to **PostgreSQL** instead of SQLite to support horizontal scaling of manager nodes. The PostgreSQL database lets you share the state of multiple managers. For more information, review [Default appsettings.json](./monitor.mdx#default-appsettingsjson).
:::
The following steps add to the previous section, where worker nodes were already scaled.
1. Locate the manager configuration file. In a default installation, the file is located at:
```
C:\Program Files\Pdftools\Pdftools OCR Service\PdftoolsOcrService\appsettings.json
```
1. Configure **PostgreSQL**:
```json
{
"Database": {
"DatabaseType": "PostgreSql",
"ConnectionString" : "User ID=myUser;Password=mySecurePassword;Server=my.database.com;Port=5432;Database=ocr-service-db;",
"DeleteJobsAfterDays": 2
}
}
```
1. Install manager nodes on separate hosts.
1. Configure a load balancer for the manager nodes.
---
## Update Pdftools OCR Service
import DownloadNonPadded from '/img/download-nopadding.svg';
To update to a new version, follow these steps:
1. Log in to the [Pdftools Portal](https://portal.pdf-tools.com/).
1. On the **Products** page, next to the Pdftools OCR Service, click **Get started** or **See product**.
1. In the **Product kits** section, find the latest `PdftoolsOcrService-VERSION_NUMBER.msi` package, and then click **Download
| Version | Bit version |
| ------------------------------------------------------- | ----------- |
| Windows Client 7+ | x86 and x64 |
| Windows Server 2008, 2008 R2, 2012, 2012 R2, 2016, 2019 | x86 and x64 |
| Version | Bit version |
| ------------ | ------------- |
| macOS 10.10+ | x64 and arm64 |
| Version | Bit version |
| ----------------- | ----------- |
| Red Hat | x64 |
| CentOS 9+ | x64 |
| Ubuntu 22.04+ | x64 |
| Oracle Linux 8+ | x64 |
| Fedora 29+ | x64 |
| Debian 10+ | x64 |
| Linux kernel 2.6+ | x64 |
| GCC Toolset 4.8+ | x64 |
| glibc 2.34+ | x64 |
---
## Formats & conformance
The PDF Toolkit SDK supports these formats:
| PDF | Image | Font |
| --------------------------- | -------- | -------------- |
| PDF 1.x (PDF 1.0 - PDF 1.7) | BMP | Type1 |
| PDF 2.0 | DIB | TrueType |
| PDF/A-1 | JPEG | OpenType |
| PDF/A-2 | JPEG2000 | OpenType (CFF) |
| PDF/A-3 | JBIG2 | |
| FDF | PNG | |
| | GIF | |
| | TIFF | |
It generates PDF files that conform to these standards:
- ISO 32000-1 (PDF 1.7)
- ISO 32000-2 (PDF 2.0)
- ISO 19005-1 (PDF/A-1)
- ISO 19005-2 (PDF/A-2)
- ISO 19005-3 (PDF/A-3)
:::note
This product is the successor of the 3-Heights® PDF Toolbox API. For the task of migrating existing projects from
3-Heights®, see the [migration guide](migration-guide/README.mdx).
:::
## PDF Toolbox SDK and Toolbox add-on
**PDF Toolbox SDK** is a standalone product that is maintained under LTS support. The **Toolbox add-on** is an add-on for the **Pdftools SDK** that lets you implement the same functionality as the **PDF Toolbox SDK** and receive new feature updates. With the **Toolbox add-on** you can use the same license key as the **Pdftools SDK**. For more information, review [Getting started with the Toolbox add-on](../pdf-tools-sdk/getting-started/toolbox/) and [Toolbox Code samples](../pdf-tools-sdk/code-samples/pdftools-sdk-toolbox-samples/).
---
## Code samples
Here you'll find some samples to get you started with the PDF Toolbox SDK.
import { CodeSamples } from '@site/src/components/CodeSamples'
## NuGet package
NuGet is a package manager that facilitates the integration of libraries for software development in .NET.
The NuGet package for the PDF Toolbox SDK contains all the libraries needed, managed and native, for all supported operating systems.
You can get the NuGet package `PdfTools.PdfToolbox.4.0.1.nupkg` directly from [https://www.nuget.org/](https://www.nuget.org/) or download it from the Pdftools website.
In Microsoft Visual Studio, this is the default location for downloading packages.
The `PdfTools.PdfToolbox.4.0.1.nupkg` package contains .NET libraries with version .NET Standard 2.0, and native libraries for Windows, macOS and Linux.
The required native libraries are loaded automatically. All project platforms are supported, including `AnyCPU`.
To use the SDK, you need to [register your license key](register-license-key.mdx).
:::note
This NuGet package is only supported on a subset of the operating systems supported by .NET Core. See [operating systems](../README.mdx#interfaces)
:::
:::info
The PDF Toolbox SDK requires **Java version 7 or higher**.
For more information on compilation and execution with the Java interface, see [PDF Toolbox SDK for Java](../sdk-java.mdx).
:::
## ZIP package
You install the PDF Toolbox SDK for Java using a ZIP archive.
:::caution
Ensure that your system matches one of the supported [operating systems](../README.mdx#interfaces).
:::
1. Log in to your account on Pdftools website and download the ZIP archive and the license key for the PDF Toolbox SDK.
2. Unzip the archive to a local directory, e.g. `C:\Program Files\PDF Tools AG\`.
This creates the following subdirectories:
| Subdirectory | Description |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `lib` | Contains the runtime executable binaries and runtime import libraries: `win-x86\PdfToolbox.dll` and `win-x86\PdfToolbox.lib` for 32-bit Windows `win-x64\PdfToolbox.dll` and `win-x64\PdfToolbox.lib` for 64-bit Windows |
| `doc` | Contains documentation |
| `jar` | Contains Java archive file `com.pdf_tools.fourheights.pdftoolbox.jar`. |
3. You may want to add the `lib\win-x64` or `lib\win-x86` subdirectory to the `%PATH%` environment variable.
4. To use the SDK, you need to [register your license key](register-license-key.mdx).
1. Log in to your account on Pdftools website and download the ZIP archive and the license key for the PDF Toolbox SDK.
2. Unzip the archive to a local directory, e.g, `/opt/pdftools.com/`.
This creates the following subdirectories:
| Subdirectory | Description |
| ------------ | --------------------------------------------------------------------------------------------- |
| `lib` | Contains the runtime executable binaries: `linux-x64/libPdfToolbox.so` for 64-bit Linux |
| `doc` | Contains documentation |
| `jar` | Contains Java archive file `com.pdf_tools.fourheights.pdftoolbox.jar`. |
3. You may want to create a link to the shared library from one of the standard library directories. For example,
```
ln -s /opt/pdf-tools.com/lib/linux-x86/libPdfToolbox.so /usr/lib
```
4. To use the SDK, you need to [register your license key](register-license-key.mdx).
1. Log in to your account on Pdftools website and download the ZIP archive and the license key for the PDF Toolbox SDK.
2. Unzip the archive to a local directory, e.g. `/opt/pdftools.com/`.
This creates the following subdirectories:
| Subdirectory | Description |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `lib` | Contains the runtime executable binaries: `osx-x64/libPdfToolbox.dylib` for 64-bit (Intel) macOS `osx-arm64/libPdfToolbox.dylib` for ARM (Apple Silicon) macOS |
| `doc` | Contains documentation |
| `jar` | Contains Java archive file `com.pdf_tools.fourheights.pdftoolbox.jar`. |
3. The library must have the extension `.jnilib` for use with Java. You may want to create a file link for this purpose. For example,
```
ln libPdfToolbox.dylib libPdfToolbox.jnilib
```
4. To use the SDK, you need to [register your license key](register-license-key.mdx).
The PDF Toolbox SDK for C comes as a ZIP archive.
:::important
Ensure that your system matches one of the supported [operating systems](../README.mdx#interfaces).
:::
1. Log in to your account on Pdftools website and download the ZIP archive and the license key for the PDF Toolbox SDK.
2. Unzip the archive to a local directory, e.g. `C:\Program Files\PDF Tools AG\`.
This creates the following subdirectories:
| Subdirectory | Description |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `lib` | Contains the runtime executable binaries and runtime import libraries: `win-x86\PdfToolbox.dll` and `win-x86\PdfToolbox.lib` for 32-bit Windows `win-x64\PdfToolbox.dll` and `win-x64\PdfToolbox.lib` for 64-bit Windows |
| `include` | Contains the header files to include in your C/C++ project. The main header `PdfToolbox.h` includes all the other headers. |
3. You may want to add the `lib\win-x64` or `lib\win-x86` subdirectory to the `%PATH%` environment variable.
4. To use the SDK, you need to [register your license key](register-license-key.mdx).
1. Log in to your account on Pdftools website and download the ZIP archive and the license key for the PDF Toolbox SDK.
2. Unzip the archive to a local directory, e.g. `/opt/pdftools.com/`.
This creates the following subdirectories:
| Subdirectory | Description |
| ------------ | -------------------------------------------------------------------------------------------------------------------------- |
| `lib` | Contains the runtime executable binaries: `linux-x64/libPdfToolbox.so` for 64-bit Linux |
| `include` | Contains the header files to include in your C/C++ project. The main header `PdfToolbox.h` includes all the other headers. |
3. You may want to create a link to the shared library from one of the standard library directories. For example:
```
ln -s /opt/pdf-tools.com/lib/linux-x64/libPdfToolbox.so /usr/lib
```
4. To use the SDK, you need to [register your license key](register-license-key.mdx).
1. Log in to your account on Pdftools website and download the ZIP archive and the license key for the PDF Toolbox SDK.
2. Unzip the archive to a local directory, e.g. `/opt/pdftools.com/`.
This creates the following subdirectories:
| Subdirectory | Description |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `lib` | Contains the runtime executable binaries: `osx-x64/libPdfToolbox.dylib` for 64-bit (Intel) macOS `osx-arm64/libPdfToolbox.dylib` for ARM (Apple Silicon) macOS |
| `include` | Contains the header files to include in your C/C++ project. The main header `PdfToolbox.h` includes all the other headers. |
3. You may want to create a link to the shared library from one of the standard library directories. For example (for an Intel processor Mac):
```
ln -s /opt/pdf-tools.com/lib/osx-x64/libPdfToolbox.dylib /usr/lib
```
4. To use the SDK, you need to [register your license key](register-license-key.mdx).
## Install color profiles
Most systems have preinstalled color profiles available. If no color profiles are available, default profiles for both RGB and CMYK are generated on the fly by the PDF Toolbox SDK.
Color profiles can also be downloaded from the following websites:
- http://www.pdf-tools.com/public/downloads/resources/colorprofiles.zip
- http://www.color.org/srgbprofiles.html
- https://www.adobe.com/support/downloads/iccprofiles/iccprofiles_win.html
For device RGB colors, a color profile `sRGB Color Space Profile.icm`, and for device CMYK, a profile `USWebCoatedSWOP.icc` are searched for in the following directories (recursively, in the order specified).
To install a color profile, download and copy the profile to the corresponding folder:
1. `%SystemRoot%\System32\spool\drivers\color`
2. Directory `Icc`, which must be a direct subdirectory of where the `PdfToolboxAPI.dll` resides.
1. `$PDF_ICC_PATH` if the environment variable is defined
2. The current working directory
1. `$PDF_ICC_PATH` if the environment variable is defined
2. The current working directory
## Temp files directory
This directory for temporary files is used for data specific to one instance of a program. The data is not shared between different invocations and deleted after termination of the program.
The directory depends on the operating system. The product checks for the existence of environment variables in the following order and uses the first path found:
1. The path specified by the `%TMP%` environment variable.
2. The path specified by the `%TEMP%` environment variable.
3. The path specified by the `%USERPROFILE%` environment variable.
4. The Windows directory.
1. The path specified by the `$PDFTMPDIR` environment variable.
2. The path specified by the `$TMP` environment variable.
3. The `/tmp` directory.
1. The path specified by the `$PDFTMPDIR` environment variable.
2. The path specified by the `$TMP` environment variable.
3. The `/tmp` directory.
## Cache directory
The cache directory is used for data that is persisted and shared between different invocations of a program. The actual caches are created in subdirectories. The content of this directory can safely be deleted to clean all caches.
This directory should be writable by the application. Otherwise, caches cannot be created or updated and performance degrades significantly.
- If the user has a profile: `%LOCAL_APPDATA%\PDF Tools AG\Caches`
- If the user has no profile: `\PDF Tools AG\Caches`
- If the user has a home directory: `~/.pdf-tools/Caches`
- If the user has no home directory: `/pdf-tools/Caches` where `` refers to the [directory for temporary files](#temp-files-directory)
- If the user has a home directory: `~/.pdf-tools/Caches`
- If the user has no home directory: `/pdf-tools/Caches` where `` refers to the [directory for temporary files](#temp-files-directory)
---
## Install fonts for the SDK
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
When text is created by the PDF Toolbox SDK, all fonts from the [Font directories](#font-directories) can be used.
{/*Add more context on what fonts are used for and why*/}
## Install system fonts
On Windows, macOS, and Linux, when a font is installed, it is by default installed only for a particular user. It is important to either install
fonts for all users, or make sure the PDF Toolbox SDK is run under that user and the user profile is loaded.
For Linux, it is recommended you use Font Manager to install all system fonts.
## Font directories
The location of the font directories depends on the operating system. Font directories are traversed recursively in the order as specified below.
If two fonts with the same name are found, the latter one takes precedence, i.e. user fonts always take precedence over system fonts.
1. `%SystemRoot%\Fonts`
2. User fonts listed in the registry key `\HKEY_CURRENT_USER\Software\Microsoft\Windows NT\CurrentVersion\Fonts`. This includes user-specific fonts from `C:\Users\\AppData\Local\Microsoft\Windows\Fonts` and app specific fonts from `C:\Program Files\WindowsApps`
3. `Fonts` directory, which must be a direct subdirectory of where `PdfToolboxAPI.dll` resides.
1. `/usr/share/fonts`
2. `/usr/local/share/fonts`
3. `~/.fonts`
4. `$PDFFONTDIR or /usr/lib/X11/fonts/Type1`
1. `/System/Library/Fonts`
2. `/Library/Fonts`
## Font cache
A cache of all fonts in all font directories is created. If fonts are added or removed from the font directories, the cache is updated automatically.
To achieve optimal performance, make sure that the cache directory is writable for the PDF Toolbox SDK. Otherwise, the font cache cannot be updated and the font directories have to be scanned on each program startup.
The font cache is created in the subdirectory `/Installed Fonts` of the [cache directory](./README.mdx#cache-directory).
---
## Register license key
To obtain an evaluation license key or full license key, contact the Pdftools sales team through the [Contact page](https://www.pdf-tools.com/contact/).
Set the license key by using the `Sdk.Initialize` method before calling the library.
:::note
The PDF Toolbox SDK and the Pdftools SDK differ in how they provide free or trial license keys (also called evaluation license keys in Pdftools).
- PDF Toolbox SDK: Contact the Pdftools sales team through the [Contact page](https://www.pdf-tools.com/contact/) to get an evaluation or full license key for the PDF Toolbox SDK. The evaluation license key is necessary to try the PDF Toolbox SDK.
- Pdftools SDK: You can try the Pdftools SDK without a license key with watermarked output files. To remove the watermark from the output files, contact the Pdftools sales team through the [Contact page](https://www.pdf-tools.com/contact/) to get a full license. No evaluation license key is necessary to try the Pdftools SDK.
:::
---
## C interface changes for PDF Toolbox SDK
There are several changes in naming and behavior in the C interface to bear in mind when migrating from the 3-Heights® PDF Toolbox API to the PDF Toolbox SDK.
## Prefixes
The name of all interface elements such as declared structs and functions, starts with a prefix. In 3-Heights® PDF Toolbox API PDF Toolbox API, all interface elements have the same prefix. The PDF Toolbox SDK introduces the following new prefixes:
| Prefix | Area of usage |
| ---------------- | --------------------------- |
| `Ptx` | Base prefix |
| `PtxGeom` | Geometric related |
| `PtxGeomReal` | For floating point numbers |
| `PtxGeomInteger` | For integer numbers |
| `PtxPdf` | General PDF related |
| `PtxPdfAnnots` | Annotation related |
| `PtxPdfContent` | Page content related |
| `PtxPdfForms` | Form field related |
| `PtxPdfNav` | Document navigation related |
## The Sdk functions
### License keys and product version
In 3-Heights® PDF Toolbox API, `PdfSetLicenseKey` and `PdfGetProductVersion` functions allows setting a license key and querying the version of the API.
In the, this functionality has been moved to the class `TPtx_Sdk`. Specifically:
- `Ptx_Sdk_Initialize` must be called to set a license key. See also [License keys](./README.mdx#license-keys).
- `Ptx_Sdk_GetVersion` gets the API’s version number as a string.
### The PDF Producer entry
In 3-Heights® PDF Toolbox API, when creating a PDF, the `TPdfMetadata` object sets the PDF’s “Producer” entry via the related function `PdfMetadataSetProducer`.
In the PDF Toolbox SDK, the class `TPtxPdf_Metadata` has no related function `PtxPdf_Metadata_SetProducer`. Instead, the “Producer” entry for all output PDFs is preconfigured as a string consisting of two parts:
1. The first part (the “base” part) is encoded in the license key. Hence, this part is determined when buying a licensef rom Pdftools.
2. The second part (the “suffix” part) is configured when calling `Ptx_Sdk_Initialize` as an argument. It is recommended to use the suffix solely for version information.
The assembled “Producer” entry can be obtained after calling `Ptx_Sdk_Initialize` using the related function `Ptx_Sdk_GetProducerFullName`.
## Closing and releasing
In 3-Heights® PDF Toolbox API, all native objects support a “closing” operation by means of the `PdfClose` function.
In the PDF Toolbox SDK, only the following classes support closing by means of a dedicated function:
- `TPtxPdf_Document`
- `TPtxPdfContent_ContentGenerator`
- `TPtxPdfContent_TextGenerator`
Specifically, the objects on which these classes operate are not fully constructed until closing. For all other objects, associated resources can be freed by calling `Ptx_Release`. Using an object after releasing results in undefined behavior.
## Elements changed to class or struct
The following 3-Heights® PDF Toolbox API structs have changed to opaque classes in the PDF Toolbox SDK:
- `TPdfEncryptionParams` → `TPtxPdf_Encryption`
- `TPdfFillParams` → `TPtxPdfContent_Fill`
- `TPdfStrokeParams` → `TPtxPdfContent_Stroke`
- `TPdfTransparencyParams` → `TPtxPdfContent_Transparency`
Hence, such objects cannot be allocated on the stack. The related initialization functions `...Initialize` have been removed. In turn, they receive allocation functions `...New`.
As a consequence, the following functions now directly return a pointer to the object:
- `PtxPdfContent_Paint_GetTransparency`
- `PtxPdfContent_PathElement_GetFill`
- `PtxPdfContent_PathElement_GetStroke`
- `PtxPdfContent_TextFragment_GetFill`
- `PtxPdfContent_TextFragment_GetStroke`
Conversely, the following 3-Heights® PDF Toolbox API class has changed to an explicitly defined struct in the PDF Toolbox SDK:
- `TPdfTransformation` → `TPtxGeomReal_AffineTransform`
Hence, such objects can be allocated on the stack. See also [Affine transform objects should be initialized](#affine-transform-objects-should-be-initialized).
As a consequence, the following functions take a last argument `TPtxGeomReal_AffineTransform`\*, a pointer to an already allocated struct:
- `PtxPdfContent_TextFragment_GetTransform`
- `PtxPdfContent_ContentElement_GetTransform`
## Renaming
Some interface elements have been renamed in addition to the introduction of new Prefixes. The following principles apply:
- Interface elements that include abbreviations are now written consistently in Pascal case, e.g. `RGB → Rgb`, except for two-letter abbreviations, which are written as two capital letters, e.g. `IO`.
- Some abbreviations have been changed to full words, e.g. `Char → Character`.
- Some words that are repeated in the introduced prefix namespace have been dropped, e.g.`TPdfAnnotationPopup` → `TPtxPdfAnnots_Popup`.
- List appending function are renamed: `...Append→...Add`.
- Improved clarity, brevity, jargon, and technical correctness.
## Affine transform objects should be initialized
In 3-Heights® PDF Toolbox API, `TPdfTransformation` is a “class”. In the PDF Toolbox SDK, this element has been renamed to `TPtxGeomReal_AffineTransformation`, and its type has changed to “struct”.
See [Elements changed to class or struct](#elements-changed-to-class-or-struct).
Specifically, default constructed `TPtxGeomReal_AffineTransform` objects are not valid. (A matrix with all values0is singular.) Default constructed `TPtxGeomReal_AffineTransform` objects should always be initialized with `PtxGeomReal_AffineTransform_GetIdentity`.
For example:
```
TPtxGeomReal_AffineTransform transform;
PtxGeomReal_AffineTransform_GetIdentity(&transform);
```
## Creation and copying methods
In 3-Heights® PDF Toolbox API, most document-associated objects are created in an output document by related functions `PdfDocumentCreate...` and copied from an input document to an output document by related functions `PdfDocumentCopy...`, e.g. `PdfDocumentCreatePage`, `PdfDocumentCopyPage`.
In the PDF Toolbox SDK, all these related functions have been moved from the `TPdfDocument` class to the class that is created or copied. For example, related function `PdfDocumentCreatePage` → `PtxPdf_Page_Create`. This affects the following classes:
- `TPdfPage`
- `TPdfImage`
- `TPdfImageMask`
- `TPdfFont`
- `TPdfGroup`
- `TPdfColorSpace`
- `TPdfPaint`
- `TPdfText`
- `TPdfMetadata`
- `TPdfFileReference`
- `TPdfSubForm`
- `TPdfGeneralTextField`
- `TPdfCombTextField`
- `TPdfCheckBoxField`
- `TPdfRadioButtonField`
- `TPdfListBoxField`
- `TPdfComboBoxField`
- `TPdfNamedDestination`
- `TPdfOutlineItem`
- `TPdfAnnotation`
- `TPdfLink`
- `TPdfFileAttachmentAnnotation`
- `TPdfFreeTextAnnotation`
- `TPdfStickyNoteAnnotation`
- `TPdfTextStampAnnotation`
- `TPdfCustomStampAnnotation`
- `TPdfCircleAnnotation`
- `TPdfSquareAnnotation`
- `TPdfLineAnnotation`
- `TPdfPolyLineAnnotation`
- `TPdfPolygonAnnotation`
- `TPdfFreeDrawingAnnotation`
- `TPdfContentElement`
- `TPdfFormFieldNode`
## Constructors
In 3-Heights® PDF Toolbox API, some document-associated objects are created by means of a constructor. For example: `PdfNewFitPageDestination`.
In the PDF Toolbox SDK, most of these document-associated objects are now created and copied with related functions `..._Create` and `..._Copy`.
This affects the following classes:
- `TPdfEmbeddedPdfLink`
- `TPdfFitHeightDestination`
- `TPdfFitPageDestination`
- `TPdfFitRectangleDestination`
- `TPdfFitWidthDestination`
- `TPdfLocationZoomDestination`
- `TPdfWebLink`
In the PDF Toolbox SDK, the following classes (most of them not document-associated) have constructors:
- `TPtxPdf_Encryption`
- `TPtxPdfContent_ContentExtractor`
- `TPtxPdfContent_ContentGenerator`
- `TPtxPdfContent_Fill`
- `TPtxPdfContent_PageCopyOptions`
- `TPtxPdfContent_PathGenerator`
- `TPtxPdfContent_Path`
- `TPtxPdfContent_Stroke`
- `TPtxPdfContent_TextGenerator`
- `TPtxPdfContent_Transparency`
- `TPtxPdfNav_OutlineCopyOptions`
All constructors have been renamed:
`PdfNew‹Type›` → `‹Prefix›_‹Type›_New`
## Unknown PDF conformance
In 3-Heights® PDF Toolbox API, the `TPdfConformance` enumeration has a value `ePdfUnk`. The PDF Toolbox SDK enum `TPtxPdf_Conformance` has no such value.
The handling of unknown (i.e. automatically upgrading) PDF conformance is now done as follows:
- In the related function `PtxPdf_Document_Create`, the type of the second argument has changed from `TPdfConformance` to `TPtxPdf_Conformance`\*, where a `NULL` value has the same meaning as the removed value `ePdfUnk`.
- The related function `PtxPdf_Document_GetConformance` always returns the current conformance. For input documents, this is the claimed conformance. For output documents, this is either the explicit conformance set when creating, or (if created with `NUL`L), the conformance the output PDF would have if closed now.
## Copy options
In 3-Heights® PDF Toolbox API, page copying and outline copying behavior is configurable by means of the `TPdfCopyOption` enum.
In the PDF Toolbox SDK, this enum has been substituted by new classes:
- `TPtxPdf_PageCopyOptions` Used in related functions `PtxPdf_Page_Copy` and `PtxPdf_Group_CreateFromPage`.
- `TPtxPdfNav_OutlineCopyOptions`
- Used in related function `PtxPdfNav_OutlineItem_Copy`.
Each copying configuration decision is reflected in a class member. Apart from `BOOL for on-off decisions, the following enumerations model possible choices:
- `TPtxPdf_CopyStrategy`
- `TPtxPdf_RemovalStrategy`
- `TPtxPdf_NameConflictResolution`
- `TPtxPdfForms_FormFieldCopyStrategy`
- `TPtxPdfNav_NamedDestinationCopyStrategy`
This clarifies the copying behavior and allows sensible default values.
## Color space classes
**Class hierarchy**
In 3-Heights® PDF Toolbox API, there is a single class `TPdfColorSpace`, which covers all types of color spaces.
In the PDF Toolbox SDK, there are the following new classes, all extending `TPtxPdfContent_ColorSpace`:
- `TPtxPdfContent_CalibratedGrayColorSpace`
- `TPtxPdfContent_CalibratedRgbColorSpace`
- `TPtxPdfContent_DeviceCmykColorSpace`
- `TPtxPdfContent_DeviceGrayColorSpace`
- `TPtxPdfContent_DeviceRgbColorSpace`
- `TPtxPdfContent_IccBasedColorSpace`
- `TPtxPdfContent_IndexedColorSpace`
- `TPtxPdfContent_LabColorSpace`
- `TPtxPdfContent_NChannelColorSpace`
- `TPtxPdfContent_SeparationColorSpace`
The 3-Heights® PDF Toolbox API color space type“DeviceN”now is subsumed by the more generalTPtxPdfContent_NChannelColorSpace.
**Device color spaces versus process color spaces**
In 3-Heights® PDF Toolbox API, the related function `PdfDocumentCreateDeviceColorSpace` does not necessarily create a device color space, e.g., in case of PDF/A.
In the PDF Toolbox SDK, the enumeration `TPdfDeviceColorSpaceType` has been renamed to `TPtxPdfContent_ProcessColorSpaceType`. The struct `TPtxPdfContent_ColorSpace` now has the following related function:
```
TPtxPdfContent_ColorSpace* PtxPdfContent_ColorSpace_CreateProcessColorSpace(TPtxPdf_Document*,
TPtxPdfContent_DeviceColorSpaceTypeiType)
```
This method creates either a device color space, or, in case of PDF/A, a calibrated (grayscale or RGB) or an ICC-based(CMYK) color space.
## Embedded/Associated/Attached files
In 3-Heights® PDF Toolbox API, embedded files, associated files, and files contained in a `TPdfFileAttachmentAnnotation` are jointly listed in the related function `PdfDocumentGetEmbeddedFiles`.
In the PDF Toolbox SDK, embedded files, associated files, and files contained in fileattachment annotations are treated separately. `ATPtxPdf_Document` now has two lists for appending:
- `PtxPdf_Document_GetAssociatedFiles`
- `PtxPdf_Document_GetPlainEmbeddedFiles`
The former related function `PdfDocumentGetEmbeddedFiles` has been renamed to `PtxPdf_Document_GetAllEmbeddedFiles`, a read-only list that contains embedded files and files contained in `TPtxPdfAnnots_FileAttachment` annotations. This list is equivalent to what a viewer normally lists in an embedded files pane. For example, the “Attachments” pane in the Adobe PDF viewer.
## Annotations
In the PDF Toolbox SDK, the following annotation classes have been renamed for technical correctness:
- `TPdfFreeDrawingAnnotation` → `TPtxPdfAnnots_InkAnnotation`
- `TPdfCircleAnnotation` → `TPtxPdfAnnots_EllipseAnnotation`
- `TPdfSquareAnnotation` → `TPtxPdfAnnots_RectangleAnnotation`
The related functions `PdfRadioButtenFieldGetCanToggleOff` and `PdfRadioButtenFieldSetCanToggleOff` have been removed. In most PDF viewers, there is no support for this feature.
**Class hierarchy**
In 3-Heights® PDF Toolbox API, `TPdfWidget` and `TPdfLink` extend the base class `TPdfAnnotation`.
In the PDF Toolbox SDK, the classes `TPtxPdfForms_Widget` and `TPtxPdfNav_Link` have been separated from their former base class. Due to this separation:
`ATPtxPdf_Page` now has the following lists:
- `PtxPdf_Page_GetAnnotations`
- `PtxPdf_Page_GetLinks`
- `PtxPdf_Page_GetFormFieldWidgets`
The following related functions of `TPtxPdfAnnots_Annotation` have been replicated for `TPtxPdfForms_Widget` and `TPtxPdfNav_Link`:
`..._GetBoundingBox`
`..._GetHidden`
`..._GetNoPrint`
The intermediate base classes `TPdfPolyDrawingAnnotation` and `TPdfShapeDrawingAnnotation` havebeen removed. All drawing annotations now directly extend the class `TPtxPdfAnnots_DrawingAnnotation`.Those drawing annotations that have a closed path (`TPtxPdfAnnots_PolygonAnnotation`,`TPtxPdfAnnots_EllipseAnnotation`,`TPtxPdfAnnots_RectangleAnnotation`) have related functions `...GetFill` and `...SetFill`.
**Class hierarchy comparison**
| 3-Heights® PDF Toolbox (left) | PDF Toolbox SDK (right) |
| ----------------------------- | ----------------------- |
## MaxLength in text fields
In 3-Heights® PDF Toolbox API, the error behavior of the related function `PdfTextFieldSetMaxLength` depends on the actual underlying class: `TPdfGeneralTextField` allows `NULL` values, while `TPdfCombTextField` does not.
In the PDF Toolbox SDK, the related functions `PdfTextFieldGetMaxLength` and `PdfTextFieldSetMaxLength` havebeen removed and replicated in the derived classes `TPtxPdfForms_CombTextField` and `TPtxPdfForms_GeneralTextField`, in the latter as a nullable `int`\*.
## Unified paint creation
In 3-Heights® PDF Toolbox API, there exist three related functions for creating a `TPdfPaintobject:
PdfDocumentCreateSolidPaint
PdfDocumentCreateAlphaPaint
PdfDocumentCreateBlendingPaint
In the PDF Toolbox SDK, these related functions have been replaced by a single related functionPtxPdfContent_Paint_Create.See also [Creation and copying methods](#creation-and-copying-methods).
## Separate inside rule from path
In 3-Heights® PDF Toolbox API, the related function `PdfNewPath` has an argument `TPdfInsideRuleiRule`.
In the PDF Toolbox SDK, this argument is dropped. Instead, the `TPdfInsideRule` now is specified in a new member of `TPtxPdfContent_Fill` when painting the path with `PtxPdfContent_ContentGenerator_PaintPath`, or it is specified in a method argument when clipping with `PtxPdfContent_ContentGenerator_ClipWithPath`.This removes ambiguity and allows a separated treatment of the insiderule for path filling and path clipping.
## Path and text clipping operations
In 3-Heights® PDF Toolbox API, the `TPdfContentGenerator` supports simultaneous clipping and painting operations.
In the PDF Toolbox SDK, path and text clipping operations have been separated from path and text painting operations as follows:
- The argument `BOOL` `bIntersectClipPath` has been removed from the related function `PdfContentGeneratorPaintPath`.
- The related function `PdfTextGeneratorSetRendering` has been removed (see also [Text generator](#text-generator)), and its argument `BOOL` `bIntersectClipping` has been dropped without a replacement.
- The new class `TPtxPdfContent_ContentGenerator` has two new methods for path and text clipping operations:
`PtxPdfContent_ContentGenerator_ClipWithPath`
`PtxPdfContent_ContentGenerator_ClipWithText`
To achieve the same effect of simultaneous clipping and painting, the painting operation has to precede the clipping operation.
## Text generator
In the PDF Toolbox SDK, the related function `PdfTextGeneratorSetRendering` has been substituted by two separate related functions:
- Related function `PtxPdfContent_TextGenerator_SetFill`
- Related function `PtxPdfContent_TextGenerator_SetStroke`
## Image size and image mask size
In 3-Heights® PDF Toolbox API, `TPdfImage` and `TPdfImageMask` have related functions `...GetWidth` and `...GetHeight`.
In the PDF Toolbox SDK, these are substituted by related functions `PtxPdfContent_Image_GetSize` and `PtxPdfContent_ImageMask_GetSize`, both of which have the new type `TPtxGeomInt_Size`.
---
## Reference
For all changes in the C interface between 3-Heights® PDF Toolbox API and the PDF Toolbox SDK, see **[C Reference](c-reference.mdx)**.
---
## Migrating from 3-Heights® PDF Toolbox API to the PDF Toolbox SDK
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
This guide explains how to migrate from 3-Heights® PDF Toolbox API (version 6.12) to the PDF Toolbox SDK (version 2.2 and higher).
Follow these steps to migrate your project to the PDF Toolbox SDK:
1. Read the [overview](#overview) and [changes for your chosen interface](#changes-to-the-interface), and adapt your project accordingly.
2. Use the [source code migration script](use-migration-script.mdx) initiate source code migration. This step can alternatively be done manually with the help of the reference.
3. Refer to [interface changes](#changes-to-the-interface) to update your code to reflect incompatible interface changes and changed functional behavior. The [source code migration script](use-migration-script.mdx) can help you in this step by marking code that needs attention.
4. Run your tests. For many changes, **making the source code compile does not guarantee the same behavior**. As an additional source of correct usage of the PDF Toolbox SDK, [source code samples](../code-samples/README.mdx) are available.
---
## Overview
Despite a general similarity in packaging, platform support, programming language bindings, and API, there are significant differences between 3-Heights® PDF Toolbox API and the PDF Toolbox SDK.
## Packaging
The 3-Heights® PDF Toolbox API comes as four different ZIP archives `PdfToolbox-API-‹version›-‹platform›.[zip|tar.gz]`, one for each platform.
The PDF Toolbox SDK comes as a single ZIP archive `PdfToolbox_C-‹version›.zip`.
The 3-Heights® PDF Toolbox API comes as a NuGet package, which targets
- .NET Framework 2.0 and higher
- .NET Standard 1.1
- .NET Standard 2.0
The PDF Toolbox SDK comes as a NuGet package, which targets
- .NET Standard 2.0
All NuGet packages are hosted on [https://www.nuget.org](https://www.nuget.org).
| 3-Heights® PDF Toolbox API | PDF Toolbox SDK |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 3-Heights® PDF Toolbox JAR file `PdfToolboxAPI.jar` | PDF Toolbox JAR file `com.pdf_tools.fourheights.pdftoolbox.jar` |
| The 64-bit native library for the respective platform: `PdfToolboxAPI.dll`, `libPdfToolboxAPI.so`, or `libPdfToolboxAPI.dylib`. (For Windows, also the 32-bit library.) | The native libraries for all supported platforms (Windows 64-bit and 32-bit, Linux 64-bit, macOS 64-bit): `PdfToolbox.dll`, `libPdfToolbox.so`, `libPdfToolbox.dylib` |
| A graphical license management tool or the license management shell tool | The license management tools are no longer necessary. See [License keys](#license-keys) |
| Manual and JavaDoc API reference | Manual and JavaDoc API reference |
| Samples | Samples are no longer provided in the kit, but are available [online](../code-samples/README.mdx). |
| 3-Heights® PDF Toolbox API | PDF Toolbox SDK |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [C header files](#c-header-files) | [C header files](#c-header-files) |
| The 64-bit native library for the respective platform: `PdfToolboxAPI.dll`, `libPdfToolboxAPI.so`, or `libPdfToolboxAPI.dylib`. (For Windows, also the 32-bit library.) | The native libraries for all supported platforms (Windows 64-bit and 32-bit, Linux 64-bit, macOS 64-bit): `PdfToolbox.dll`, `libPdfToolbox.so`, `libPdfToolbox.dylib` |
| A graphical license management tool or the license management shell tool | The license management tools are no longer necessary. See [License keys](#license-keys) |
| Manual | Manual |
| Samples | Samples are no longer provided in the kit, but are available [online](../code-samples/README.mdx). |
## C header files
In 3-Heights® PDF Toolbox API, there is one main header `filepdftoolboxapi_c.h`, which included the additional header `filespdfcdecl.h`, `pdfcopydecl.h`, `pdffiledecl.h`, `pdfintfdecl.h`, and `pdfsecuritydecl.h`.
In the PDF Toolbox SDK, there is one main header `filePdfToolbox.h`, which includes the following subheader files:
- `PdfToolbox_Platform.h`: A platform abstraction header file.
- `PdfToolbox_Types.h`: Declaration of all types.
- `PdfToolbox_‹prefix›.h`: Subheader file for each ‹prefix› (seePrefixes), containing function declarations.
## License keys
The 3-Heights® PDF Toolbox API supports the installation of machine-bound license 3-Heights® license keys by means of the graphical tool `LicenseManager.exe` for Windows or the shell `toollicmgr` for all platforms.
The PDF Toolbox SDK does not support installed keys anymore. Instead, a license key must be provided at application initialization time. See also `The Sdk functions`.Additionally, the license key has a new format: `<4H,V4,TOOLSDK,XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX>`.
## Changes to the interface
See [.NET interface](dotnet-interface.mdx)
See [Java interface](./java-interface.mdx)
See [C interface](C-interface.mdx)
---
## Reference for changes in C interface
This section lists all changes in the C interface between 3-Heights® PDF Toolbox API and the PDF Toolbox SDK. Interface elements are ordered alphabetically by PDF Toolbox SDK prefix.
## Prefix Ptx
Changes to functions that are not related to specific object types:
- Removed `functionPdfClose`. Substituted for closeable objects by explicit `..._Close` functions. See [Closing and releasing](./C-interface.mdx#closing-and-releasing).
- Removed `PdfCheckLicense`.
- Functions moved to `TPtx_Sdk`:
- `PdfSetLicenseKey`
- `PdfGetProductVersion` See [License keys and product version](./README.mdx#license-keys).
- Renamed functions:
| 3-Heights® PDF Toolbox API function | PDF Toolbox SDK function |
| ----------------------------------- | ------------------------- |
| `PdfInitialize` | `Ptx_Initialize` |
| `PdfUninitialize` | `Ptx_Uninitialize` |
| `PdfGetLastError` | `Ptx_GetLastError` |
| `PdfGetLastErrorMessage` | `Ptx_GetLastErrorMessage` |
| `PdfRelease` | `Ptx_Release` |
| `PdfEquals` | `Ptx_Equals` |
| `PdfGetHashCode` | `Ptx_GetHashCode` |
#### TPdfErrorCode
| [Enum.] `TPdfErrorCode` → `TPtx_ErrorCode` |
| ------------------------------------------------------------------------------------------------------------------------ |
| Removed enum values: `ePdfErrorInfrastructure``ePdfErrorProcessing``ePdfErrorFatal` |
| Renamed enum value: `ePdfSuccess` → `ePdf_Error_Success` `ePdfError...` → `ePdf_Error_...` |
#### TPtx_Sdk
| [Class] `TPtx_Sdk` → `TPtx_Sdk` |
| ------------------------------------------------------------------------------------------------------------------- |
| Related function: `BOOL Ptx_Sdk_Initialize(` `const char* szLicense,``const char* szProducerSuffix)` |
| Related function: `size_t Ptx_Sdk_GetVersion(``char* pBuffer,` `size_tnBufferSize)` |
| Related function: `size_t Ptx_Sdk_GetProducerFullName(``char* pBuffer,``size_tnBufferSize)` |
See the [Sdk functions](C-interface.mdx#the-sdk-functions)
#### TPdfStringMap
| [Class] `TPdfStringMap` → `TPtxPdf_StringMap` |
| --------------------------------------------------------------------------- |
| Renamed value: `PdfStringMap...` → `PtxPdf_StringMap_...` |
## Prefix PtxGeom
#### TdfRotation
| [Enum.] `TPdfRotation` → `TPtxGeom_Rotation` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed values: `ePdfRotateNoRotation` → `ePtxGeom_Rotation_None`` ePdfRotateClockwise` → `ePtxGeom_Rotation_Clockwise``ePdfRotateUpsideDown` → `ePtxGeom_Rotation_UpsideDown` `ePdfRotateCounterClockwise` → `ePtxGeom_Rotation_CounterClockwise` |
#### TPdfTextAlignment
| [Enum.] `TPdfTextAlignment` → `TPtxGeom_HorizontalAlignment` |
| ---------------------------------------------------------------------------------------------- |
| Renamed value: `ePdfTextAlignment...` → `ePtxGeom_HorizontalAlignment_...` |
### Prefix PtxGeomInt
#### TPtxGeomInt_Size
| [Struct.] `TPtxGeomInt_Size` → `TPtxGeomInt_Size` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Fields: `intiWidth` `intiHeight` Used in `TPdfImage` and `TPdfImageMask` to substitute the removed related functions `PdfImageGetWidth`, `PdfImageGetHeight`, `PdfImageMaskGetWidth`, and `PdfImageMaskGetHeight`. |
See [Image size and image mask size](C-interface.mdx#image-size-and-image-mask-size).
### Prefix PtxGeomReal
#### TPdfPoint
| [Struct.] `TPdfPoint` → `TPtxGeomReal_Point` |
| -------------------------------------------- |
#### TPdfRectangle
| [Struct.] `TPdfRectangle` → `TPtxGeomReal_Rectangle` |
| ---------------------------------------------------- |
#### TPdfSize
| [Struct.] `TPdfSize` → `PtxGeomReal_Size` |
| ----------------------------------------- |
#### TPdfTransformation
| [Class] → [Struct.] `TPdfTransformation` → `TPtxGeomReal_AffineTransform` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed related functions: `PdfNewTransformationIdentity`, `PdfNewTransformationCopy`, and `PdfNewTransformation`.Removed related function: `PdfTransformationRotate` Renamed related function: `PdfTransformationRotateAround` → `PtxGeomReal_AffineTransform_Rotate`.Renamed remaining related functions: `PdfTransformation...` → `PtxGeomReal_AffineTransform_...` New fields: `double dA` `double dB` `double dC` `double dD` `double dE` `double dF` New related function: `BOOL PtxGeomReal_AffineTransform_GetIdentity(` `TPtxGeomReal_AffineTransform* pIdentity)`. See [Affine transform objects should be initialized](C-interface.mdx#affine-transform-objects-should-be-initialized). |
See [Elements changed to class or struct](C-interface.mdx#elements-changed-to-class-or-struct)
## Prefix PtxPdf
#### TPdfConformance
| [Enum.] `TPdfConformance` → `TPtxPdf_Conformance` |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed enum value `ePdfUnk`Renamed enum values: `ePdfA1b` → `ePtxPdf_Conformance_PdfA1B``ePdfA1a` → `ePtxPdf_Conformance_PdfA1A``ePdfA2b` → `ePtxPdf_Conformance_PdfA2B``ePdfA2u` → `ePtxPdf_Conformance_PdfA2U``ePdfA2a` → `ePtxPdf_Conformance_PdfA2A``ePdfA3b` → `ePtxPdf_Conformance_PdfA3B``ePdfA3u` → `ePtxPdf_Conformance_PdfA3U``ePdfA3a` → `ePtxPdf_Conformance_PdfA3A`Renamed remaining enum values `ePdf...` → `ePtxPdf_Conformance_...` |
#### TPdfCopyOption
| [Enum.] `TPdfCopyOption` → - |
| ------------------------------------------------------------------------------------------------------------------------------------ |
| Substituted by `TPtxPdf_PageCopyOptions` and `TPtxPdfNav_OutlineCopyOptions`. See [Copy options](C-interface.mdx#copy-options). |
| [Enum.] - → `TPtxPdf_CopyStrategy` |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Values: `ePtxPdf_CopyStrategy_Copy``ePtxPdf_CopyStrategy_Flatten``ePtxPdf_CopyStrategy_Remove`Substitutes the removed `TPdfCopyOption`. |
#### TPdfDocument
| [Class] `TPdfDocument` → `TPtxPdf_Document` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related function `PdfDocumentGetOutlineItems`→ `PtxPdf_Document_GetOutline`. Changed return and argument type of related functions `PdfDocumentGetOutputIntent` and `PdfDocumentSetOutputIntent` from `TPdfColorSpace` to `TPtxPdfContent_IccBasedColorSpace`. See [Color space classes](./C-interface.mdx#color-space-classes).Renamed related function `PdfDocumentGetEmbeddedFiles` → `PtxPdf_Document_GetAllEmbeddedFiles`. Changed behavior: Appending is not supported anymore. This is a readonly list of all embedded files and all files in `TPdfFileAttachmentAnnotation`. See [Embedded/Associated/Attached files](./C-interface.mdx#embeddedassociatedattached-files).Changed behavior of related function `PdfDocumentGetConformance` → `PtxPdf_Document_GetConformance` for output documents: Always returns the current conformance instead of removed enum value `ePdfUnk`.Changed signature of related function `TPdfDocument* PdfDocumentCreate(``TPdfstream* pStreamDesc,``TPdfConformance iConformance,``TPdfEncryptionParams* pEncryption)` → `TPtxPdf_Document* PtxPdf_Document_Create(``TPtxSys_StreamDescriptor* pStreamDesc,``TPtxPdf_Conformance* pConformance,``TPtxPdf_Encryption* pEncryption)`Specifically, a `NULL` value for the second argument is now legal. See [Unknown PDF conformance](./C-interface.mdx#unknown-pdf-conformance).Removed and substituted the following related functions:`PdfDocumentCreateFileReference` → `PtxPdf_FileReference_Create``PdfDocumentCreateMetadata` → `PtxPdf_Metadata_Create``PdfDocumentCreatePage` → `PtxPdf_Page_Create``PdfDocumentCreateCircleAnnotation` → `PtxPdfAnnots_EllipseAnnotation_Create``PdfDocumentCreateCustomStampAnnotation` → `PtxPdfAnnots_CustomStamp_Create``PdfDocumentCreateFileAttachmentAnnotation` → `PtxPdfAnnots_FileAttachment_Create``PdfDocumentCreateFreeDrawingAnnotation` → `PtxPdfAnnots_InkAnnotation_Create``PdfDocumentCreateFreeTextAnnotation` → `PtxPdfAnnots_FreeText_Create``PdfDocumentCreateLineAnnotation` → `PtxPdfAnnots_LineAnnotation_Create``PdfDocumentCreatePolyLineAnnotation` → `PtxPdfAnnots_PolyLineAnnotation_Create``PdfDocumentCreatePolygonAnnotation` → `PtxPdfAnnots_PolygonAnnotation_Create``PdfDocumentCreateSquareAnnotation` → `PtxPdfAnnots_RectangleAnnotation_Create``PdfDocumentCreateStickyNoteAnnotation` → `PtxPdfAnnots_StickyNote_Create``PdfDocumentCreateTextStampAnnotationRaw` → `PtxPdfAnnots_TextStamp_CreateRaw``PdfDocumentCreateAlphaPaint`, `PdfDocumentCreateBlendingPaint`, `PdfDocumentCreateSolidPaint` → `PtxPdfContent_Paint_Create` See [Unified paint creation](./C-interface.mdx#unified-paint-creation).`PdfDocumentCreateDeviceColorSpace` → `PtxPdfContent_ColorSpace_CreateProcessColorSpace``PdfDocumentCreateFont` → `PtxPdfContent_Font_Create``PdfDocumentCreateGroup` → `PtxPdfContent_Group_Create``PdfDocumentCreateICCColorSpace` → `PtxPdfContent_IccBasedColorSpace_Create``PdfDocumentCreateImageMask` → `PtxPdfContent_ImageMask_Create``PdfDocumentCreateImage` → `PtxPdfContent_Image_Create``PdfDocumentCreateSystemFont` → `PtxPdfContent_Font_CreateFromSystem``PdfDocumentCreateText` → `PtxPdfContent_Text_Create``PdfDocumentCreateCheckBoxField` → `PtxPdfForms_CheckBoxField_Create``PdfDocumentCreateCombTextField` → `PtxPdfForms_CombTextField_Create``PdfDocumentCreateComboBoxField` → `PtxPdfForms_ComboBoxField_Create``PdfDocumentCreateGeneralTextField` → `PtxPdfForms_GeneralTextField_Create``PdfDocumentCreateListBoxField` → `PtxPdfForms_ListBoxField_Create``PdfDocumentCreateRadioButtonField` → `PtxPdfForms_RadioButtonField_Create``PdfDocumentCreateSubForm` → `PtxPdfForms_SubForm_Create``PdfDocumentCreateNamedDestination` → `PtxPdfNav_NamedDestination_Create``PdfDocumentCreateOutlineItem` → `PtxPdfNav_OutlineItem_Create``PdfDocumentCopyFileReference` → `PtxPdf_FileReference_Copy``PdfDocumentCopyMetadata` → `PtxPdf_Metadata_Copy``PdfDocumentCopyPage` → `PtxPdf_Page_Copy``PdfDocumentCopyAnnotation` → `PtxPdfAnnots_Annotation_Copy``PdfDocumentCopyColorSpace` → `PtxPdfContent_ColorSpace_Copy``PdfDocumentCopyContentElement` → `PtxPdfContent_ContentElement_Copy``PdfDocumentCopyGroupElementWithoutContent` → `PtxPdfContent_GroupElement_CopyWithoutContent``PdfDocumentCopyPageAsGroup` → `PtxPdfContent_Group_CopyFromPage``PdfDocumentCopyFormFieldNode` → `PtxPdfForms_FormFieldNode_Copy``PdfDocumentCopyViewerSettings` → `PtxPdfNav_ViewerSettings_Copy``PdfDocumentCopyOutlineItem` → `PtxPdfNav_OutlineItem_Copy` See [Creation and copying methods](././C-interface.mdx#creation-and-copying-methods).Renamed remaining related functions `PdfDocument...` → `PtxPdf_Document_...`New related function `TPtxPdf_FileReferenceList* PtxPdf_Document_GetPlainEmbeddedFiles(` `TPtxPdf_Document* )`. This is a list of all embedded files that are neither associated nor contained in a `TPdfFileAttachmentAnnotation`. See [Embedded/Associated/Attached files](./C-interface.mdx#embeddedassociatedattached-files).New related function `BOOL PtxPdf_Document_Close(``TPtxPdf_Document*)`See [Closing and releasing](./C-interface.mdx#closing-and-releasing). |
#### TPdfEncryptionParams
| [Struct.] → [Class] `TPdfEncryptionParams` → `TPtxPdf_Encryption` |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed related function `PdfEncryptionParamsInitialize`.New related function `TPtxPdf_Encryption* PtxPdf_Encryption_New(``const char* szUserPassword,``const char* szOwnerPassword,``TPtxPdf_Permission iPermissions)`.New related functions `size_t PtxPdf_Encryption_GetUserPassword(` `TPtxPdf_Encryption*,` `char* pBuffer,``size_t nBufferSize)` `size_t PtxPdf_Encryption_SetUserPassword(` `TPtxPdf_Encryption*,` `const char* szUserPassword)`. New related functions `size_t PtxPdf_Encryption_GetOwnerPassword(` `TPtxPdf_Encryption*,` `char* pBuffer,size_tnBufferSize)` `size_t PtxPdf_Encryption_SetOwnerPassword(` `TPtxPdf_Encryption*,` `const char*szOwnerPassword)`. New related functions `TPtxPdf_Permission` `PtxPdf_Encryption_GetPermissions(` `TPtxPdf_Encryption*)` `BOOL PtxPdf_Encryption_SetPermissions(` `TPtxPdf_Encryption*,` `TPtxPdf_PermissioniPermissions)`. |
#### TPdfFileReference
| [Class] `TPdfFileReference` → `TPtxPdf_FileReference` |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related function `PdfFileReference...` → `PtxPdf_FileReference_...` New related function `TPtxPdf_FileReference* PtxPdf_FileReference_Create(``TPtxPdf_Document* pTargetDocument,` `TPtxSys_StreamDescriptor* pData,` `const char* szName,` `const char* szMediaType,` `const char* szDescription,` `TPtxSys_Date* pModificationDate)` |
See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods).
#### TPdfFileReferenceList
| [Class] `PdfFileReferenceList` → `TPtxPdf_FileReferenceList` |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related function `PdfFileReferenceListAppend` → `PtxPdf_FileReferenceList_Add`.Renamed remaining related functions `PdfFileReferenceList...`→ `PtxPdf_FileReferenceList_...` |
#### TPdfMetadata
| [Class] `TPdfMetadata` → `TPtxPdf_Metadata` |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed related function `PdfMetadataSetProducer`. See The PDF Producer entry.Renamed related functions `PdfMetadata...` → `PtxPdf_Metadata_...`New related function `TPtxPdf_Metadata* PtxPdf_Metadata_Create(` `TPtxPdf_Document* pTargetDocument,` `TPtxSys_StreamDescriptor* pXmp)` See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods).New related function `TPtxPdf_Metadata* PtxPdf_Metadata_Copy(` `TPtxPdf_Document* pTargetDocument,` `TPtxPdf_Metadata* pMetadata)` See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). |
#### TPtxPdf_NameConflictResolution
| [Enum.] - → `TPtxPdf_NameConflictResolution` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Values: `ePtxPdf_NameConflictResolution_Merge``ePtxPdf_NameConflictResolution_Rename` Substitutes the removed `TPdfCopyOption` |
See [Copy options](C-interface.mdx#copy-options).
#### TPdfPage
| [Class] `TPdfPage` → `TPtxPdf_Page` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Renamed related function `PdfPageCrop` → `PtxPdf_Page_UpdateSize`.Renamed remaining related functions `PdfPage...` → `PtxPdf_Page_...`New related function `TPtxPdfForms_WidgetList* PtxPdf_Page_GetFormFieldWidgets(` `TPtxPdf_Page*)`. See [Annotations](C-interface.mdx#annotations).New related function `TPtxPdfNav_LinkList* PtxPdf_Page_GetLinks(` `TPtxPdf_Page*)`.See [Annotations](C-interface.mdx#annotations).New related function `TPtxPdf_Page* PtxPdf_Page_Create(` `TPtxPdf_Document* pTargetDocument,` `TPtxGeomReal_Size* pSize)`. See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods).New related function `TPtxPdf_Page* PtxPdf_Page_Copy(` `TPtxPdf_Document* pTargetDocument,` `TPtxPdf_Page* pPage,` `TPtxPdf_PageCopyOptions* pOptions)`. See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). |
#### TPtxPdf_PageCopyOptions
| [Class] - → `TPtxPdf_PageCopyOptions` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Related function `TPtxPdf_PageCopyOptions* PtxPdf_PageCopyOptions_New()`Related functions `TPtxPdf_CopyStrategy PtxPdf_PageCopyOptions_GetLinks(` `TPtxPdf_PageCopyOptions*)` `BOOL PtxPdf_PageCopyOptions_SetLinks(` `TPtxPdf_PageCopyOptions*,` `TPtxPdf_CopyStrategyiLinks)`Default: `ePtxPdf_CopyStrategy_Copy`Related functions `TPtxPdfForms_FormFieldCopyStrategy PtxPdf_PageCopyOptions_GetFormFields(` `TPtxPdf_PageCopyOptions*)``BOOL PtxPdf_PageCopyOptions_SetFormFields(``TPtxPdf_PageCopyOptions*,``TPtxPdfForms_FormFieldCopyStrategyiFormFields)`Default: `ePtxPdfForms_FormFieldCopyStrategy_Copy`Related functions `TPtxPdf_CopyStrategy PtxPdf_PageCopyOptions_GetSignedSignatures(``TPtxPdf_PageCopyOptions*)``BOOL PtxPdf_PageCopyOptions_SetSignedSignatures(``TPtxPdf_PageCopyOptions*,``TPtxPdf_CopyStrategyiSignedSignatures)`Default: `ePtxPdf_CopyStrategy_Copy`Related functions `TPtxPdf_CopyStrategy PtxPdf_PageCopyOptions_GetAnnotations(` `TPtxPdf_PageCopyOptions*)``BOOL PtxPdf_PageCopyOptions_SetAnnotations(` `TPtxPdf_PageCopyOptions*,` `TPtxPdf_CopyStrategyiAnnotations)`Default: `ePtxPdf_CopyStrategy_Copy`Related functions `BOOL PtxPdf_PageCopyOptions_GetCopyOutlineItems(``TPtxPdf_PageCopyOptions*)``BOOL PtxPdf_PageCopyOptions_SetCopyOutlineItems(``TPtxPdf_PageCopyOptions*,``BOOL bCopyOutlineItems)`Default: `TRUE`Related functions `BOOL PtxPdf_PageCopyOptions_GetCopyAssociatedFiles(``TPtxPdf_PageCopyOptions*)``BOOL PtxPdf_PageCopyOptions_SetCopyAssociatedFiles(``TPtxPdf_PageCopyOptions*,``BOOL bCopyAssociatedFiles)`Default: `TRUE`Related functions `BOOL PtxPdf_PageCopyOptions_GetCopyLogicalStructure(``TPtxPdf_PageCopyOptions*)``BOOL PtxPdf_PageCopyOptions_SetCopyLogicalStructure(``TPtxPdf_PageCopyOptions*,``BOOL bCopyLogicalStructure)`Default: `TRUE`Related functions `TPtxPdf_NameConflictResolution PtxPdf_PageCopyOptions_GetFormFieldConflictResolution(``TPtxPdf_PageCopyOptions*)``BOOL PtxPdf_PageCopyOptions_SetFormFieldConflictResolution(``TPtxPdf_PageCopyOptions*,``TPtxPdf_NameConflictResolution iFormFieldConflictResolution)`Default: `ePtxPdf_NameConflictResolution_Merge`Related functions `TPtxPdfNav_NamedDestinationCopyStrategy PtxPdf_PageCopyOptions_GetNamedDestinations(``TPtxPdf_PageCopyOptions*)``BOOL PtxPdf_PageCopyOptions_SetNamedDestinations(``TPtxPdf_PageCopyOptions*,``TPtxPdfNav_NamedDestinationCopyStrategy iNamedDestinations)`Default: `ePtxPdfNav_NamedDestinationCopyStrategy_Copy`Related functions `BOOL PtxPdf_PageCopyOptions_GetOptimizeResources(``TPtxPdf_PageCopyOptions*)``BOOL PtxPdf_PageCopyOptions_SetOptimizeResources(``TPtxPdf_PageCopyOptions*,``BOOL bOptimizeResources)`Default: `TRUE` Substitutes the removed `TPdfCopyOption`. See [Copy options](C-interface.mdx#copy-options). |
#### TPdfPageList
| [Class] `TPdfPageList` → `TPtxPdf_PageList` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related function `PdfPageListAppend` → `PtxPdf_PageList_Add`Renamed remaining related functions `PdfPageList...` → `PtxPdf_PageList_...` |
#### TPdfPermission
| [Enum.] `TPdfPermission` → `TPtxPdf_Permission` |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed enum values `ePermAll`, `ePermSameAsInput`, and `ePermNoEncryption`.Renamed enum values `ePerm...` → `ePtxPdf_Permission_...` |
#### TPtxPdf_RemovalStrategy
| [Enum.] - → `TPtxPdf_RemovalStrategy` |
| ------------------------------------------------------------------------------------------------------------------------------------------------ |
| Values: `ePtxPdf_RemovalStrategy_Flatten` `ePtxPdf_RemovalStrategy_Remove` Substitutes the removed `TPdfCopyOption`. |
See [Copy options](C-interface.mdx#copy-options).
### Prefix PtxPdfAnnots
#### TPdfAnnotation
| [Class] `TPdfAnnotation` → `TPtxPdfAnnots_Annotation` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related function `PdfAnnotationGetRectangle` → `PtxPdfAnnots_Annotation_GetBoundingBox` Removed related function `PdfAnnotationGetDoPrint` New related function `PtxPdfAnnots_Annotation_GetNoPrint` with reversed meaning of the removed related function `PdfAnnotationGetDoPrint`.New related function `TPtxPdfAnnots_Annotation* PtxPdfAnnots_Annotation_Copy(``TPtxPdf_Document* pTargetDocument,``TPtxPdfAnnots_Annotation* pAnnotation)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). See [Annotations](C-interface.mdx#annotations). |
#### TPdfAnnotationLineEnding
| [Enum.] `TPdfAnnotationLineEnding` → `TPtxPdfAnnots_LineEnding` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed enum value `ePdfAnnotationLineEndingReversedOpenArrow` → `ePtxPdfAnnots_LineEnding_OpenArrowTail` Renamed enum value `ePdfAnnotationLineEndingReversedClosedArrow` → `ePtxPdfAnnots_LineEnding_ClosedArrowTail`Renamed remaining enum values `ePdfAnnotationLineEnding...` → `ePtxPdfAnnots_LineEnding_...` |
#### TPdfAnnotationsList
| [Class] `TPdfAnnotationList`→ `TPtxPdfAnnots_AnnotationList` |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related function `PdfAnnotationListAppend` → `PtxPdfAnnots_AnnotationList_Add`.Renamed remaining related functions `PdfAnnotationList...` → `PtxPdfAnnots_AnnotationList_...` |
#### TPdfAnnotationPopup
| [Class] `TPdfAnnotationPopup` → `TPtxPdfAnnots_Popup` |
| ------------------------------------------------------------------------------------------------ |
| Renamed related function `PdfAnnotationPopupGetRectangle` → `PtxPdfAnnots_Popup_GetBoundingBox`. |
#### TPdfAnnotationType
| [Enum.] `TPdfAnnotationType` → `TPtxPdfAnnots_AnnotationType` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Removed enum values:`ePdfAnnotationTypeWidget``ePdfAnnotationTypeLink``ePdfAnnotationTypeInternalLink``ePdfAnnotationTypeWebLink``ePdfAnnotationTypeEmbeddedPdfLink``ePdfAnnotationTypePolyDrawingAnnotation``ePdfAnnotationTypeShapeDrawingAnnotation`Renamed enum values:`ePdfAnnotationTypeCircleAnnotation` → `ePtxPdfAnnots_AnnotationType_EllipseAnnotation``ePdfAnnotationTypeCustomStampAnnotation` → `ePtxPdfAnnots_AnnotationType_CustomStamp``ePdfAnnotationTypeFileAttachmentAnnotation` → `ePtxPdfAnnots_AnnotationType_FileAttachment``ePdfAnnotationTypeFreeDrawingAnnotation` → `ePtxPdfAnnots_AnnotationType_InkAnnotation``ePdfAnnotationTypeFreeTextAnnotation` → `ePtxPdfAnnots_AnnotationType_FreeText``ePdfAnnotationTypeHighlightAnnotation` → `ePtxPdfAnnots_AnnotationType_Highlight``ePdfAnnotationTypeSquareAnnotation` → `ePtxPdfAnnots_AnnotationType_RectangleAnnotation``ePdfAnnotationTypeSquigglyAnnotation` → `ePtxPdfAnnots_AnnotationType_Squiggly``ePdfAnnotationTypeStampAnnotation` → `ePtxPdfAnnots_AnnotationType_Stamp``ePdfAnnotationTypeStickyNoteAnnotation` → `ePtxPdfAnnots_AnnotationType_StickyNote``ePdfAnnotationTypeStrikeThroughAnnotation` → `ePtxPdfAnnots_AnnotationType_StrikeThrough``ePdfAnnotationTypeTextInsertAnnotation` → `ePtxPdfAnnots_AnnotationType_TextInsert``ePdfAnnotationTypeTextMarkupAnnotation` → `ePtxPdfAnnots_AnnotationType_TextMarkup``ePdfAnnotationTypeTextStampAnnotation` → `ePtxPdfAnnots_AnnotationType_TextStamp``ePdfAnnotationTypeUnderlineAnnotation` → `ePtxPdfAnnots_AnnotationType_Underline`Renamed remaining enum values `ePdfAnnotationType...` → `ePtxPdfAnnots_AnnotationType_...` See [Annotations](C-interface.mdx#annotations). |
#### TPdfCircleAnnotation
| [Class] `TPdfCircleAnnotation[class]` → `TPtxPdfAnnots_EllipseAnnotation` |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed base class to struct `TPtxPdfAnnots_DrawingAnnotation`. See Annotations. New related function `TPtxPdfAnnots_EllipseAnnotation* PtxPdfAnnots_EllipseAnnotation_Create(``TPtxPdf_Document* pTargetDocument,` `TPtxGeomReal_Rectangle* pBoundingBox,` `TPtxPdfContent_Stroke* pStroke,` `TPtxPdfContent_Paint* pFill)` See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods).New related function `TPtxPdfContent_Paint* PtxPdfAnnots_EllipseAnnotation_GetFill(` `TPtxPdfAnnots_EllipseAnnotation*)`.See [TPdfDrawingAnnotation](#tpdfdrawingannotation) for inherited changes. |
#### TPdfCustomStampAnnotation
| [Class] `TPdfCustomStampAnnotation` → `TPtxPdfAnnots_CustomStamp` |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related functions `PdfCustomStampAnnotation...` → `PtxPdfAnnots_CustomStamp_...`New related function `TPtxPdfAnnots_CustomStampAnnotation* PtxPdfAnnots_CustomStamp_Create(` `TPtxPdf_Document* pTargetDocument,` `TPtxGeomReal_Rectangle* pBoundingBox)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). See [TPdfStampAnnotation](#tpdfstampannotation) for inherited changes. |
#### TPdfDrawingAnnotation
| [Class] `TPdfDrawingAnnotation` → `TPtxPdfAnnots_DrawingAnnotation` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Renamed related functions `PdfDrawingAnnotation...` → `PtxPdfAnnots_DrawingAnnotation_...` See [TPdfMarkupAnnotation](#tpdfmarkupannotation) for inherited changes. |
#### TPdfDrawingAnnotationType
| [Enum.] `TPdfDrawingAnnotationType` → `TPtxPdfAnnots_DrawingAnnotationType` |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed enum values: `ePdfDrawingAnnotationTypePolyDrawingAnnotation``ePdfDrawingAnnotationTypeShapeDrawingAnnotation`Renamed enum values:`ePdfDrawingAnnotationTypeCircleAnnotation` → `ePtxPdfAnnots_DrawingAnnotationType_EllipseAnnotation``ePdfDrawingAnnotationTypeFreeDrawingAnnotation` → `ePtxPdfAnnots_DrawingAnnotationType_InkAnnotation``ePdfDrawingAnnotationTypeSquareAnnotation` → `ePtxPdfAnnots_DrawingAnnotationType_RectangleAnnotation`Renamed remaining enum values `ePdfDrawingAnnotationType...` → `ePtxPdfAnnots_DrawingAnnotationType_...` See [Annotations](C-interface.mdx#annotations). |
#### TPdfFileAttachmentAnnotation
| [Class] `TPdfFileAttachmentAnnotation` → `TPtxPdfAnnots_FileAttachment` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New related function `TPtxPdfAnnots_FileAttachmentAnnotation* PtxPdfAnnots_FileAttachment_Create(``TPtxPdf_Document* pTargetDocument,` `TPtxGeomReal_Point* pTopleft,``TPtxPdf_FileReference* pAttachedFile,``TPtxPdfContent_Paint* pPaint)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods).Renamed related functions `PdfFileAttachmentAnnotation...` → `PtxPdfAnnots_FileAttachment_...`See [TPdfMarkupAnnotation](#tpdfmarkupannotation) for inherited changes. |
#### TPdfFileAttachmentIcon
| [Enum.] `TPdfFileAttachmentIcon` → `TPtxPdfAnnots_FileAttachmentIcon` |
| ---------------------------------------------------------------------------------------- |
| Renamed enum values `ePdfFileAttachmentIcon...` → `ePtxPdfAnnots_FileAttachmentIcon_...` |
#### TPdfFreeDrawingAnnotation
| [Class] `TPdfFreeDrawingAnnotation` → `TPtxPdfAnnots_InkAnnotation` |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed base class to struct `TPtxPdfAnnots_DrawingAnnotation`. See [Annotations](C-interface.mdx#annotations).New related function `TPtxPdfAnnots_InkAnnotation* PtxPdfAnnots_InkAnnotation_Create(` `TPtxPdf_Document* pTargetDocument,` `TPtxPdfContent_Path* pPath,` `TPtxPdfContent_Stroke* pStroke)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). See [TPdfDrawingAnnotation](#tpdfdrawingannotation) for inherited changes. |
#### TPdfFreeTextAnnotation
| [Class] `TPdfFreeTextAnnotation` → `TPtxPdfAnnots_FreeText` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related functions `PdfFreeTextAnnotation...` → `PtxPdfAnnots_FreeText_...`New related function `TPtxPdfAnnots_FreeText* PtxPdfAnnots_FreeText_Create(` `TPtxPdf_Document* pTargetDocument,` `TPtxGeomReal_Rectangle* pBoundingBox,` `const char* szContent,` `TPtxPdfContent_Paint* pPaint)` See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). See [TPdfMarkupAnnotation](#tpdfmarkupannotation) for inherited changes. |
#### TPdfHighlightAnnotation
| [Class] `TPdfHighlightAnnotation` → `TPtxPdfAnnots_Highlight` |
| -------------------------------------------------------------------------------- |
| See [TPdfTextMarkupAnnotation](#tpdftextmarkupannotation) for inherited changes. |
#### TPdfLineAnnotation
| [Class] `TPdfLineAnnotation` → `TPtxPdfAnnots_LineAnnotation` |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related functions `PdfLineAnnotation...` → `PtxPdfAnnots_LineAnnotation_...`New related function `TPtxPdfAnnots_LineAnnotation* PtxPdfAnnots_LineAnnotation_Create(` `TPtxPdf_Document* pTargetDocument,` `TPtxGeomReal_Point* pStart,` `TPtxGeomReal_Point* pEnd,``TPtxPdfContent_Stroke* pStroke)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). See [TPdfDrawingAnnotation](#tpdfdrawingannotation) for inherited changes. |
#### TPdfMarkupAnnotation
| [Class] `TPdfMarkupAnnotation` → `TPtxPdfAnnots_MarkupAnnotation` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related functions `PdfMarkupAnnotation...` → `PtxPdfAnnots_MarkupAnnotation_...` See [TPdfAnnotation](#tpdfannotation) for inherited changes. |
#### TPdfMarkupAnnotationType
| [Enum.] `TPdfMarkupAnnotationType` → `TPtxPdfAnnots_MarkupAnnotationType` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed enum values: `ePdfMarkupAnnotationTypePolyDrawingAnnotation``ePdfMarkupAnnotationTypeShapeDrawingAnnotation`Renamed enum values: `ePdfMarkupAnnotationTypeCircleAnnotation` → `ePtxPdfAnnots_MarkupAnnotationType_EllipseAnnotation``ePdfMarkupAnnotationTypeCustomStampAnnotation` → `ePtxPdfAnnots_MarkupAnnotationType_CustomStamp``ePdfMarkupAnnotationTypeDrawingAnnotation` → `ePtxPdfAnnots_MarkupAnnotationType_DrawingAnnotation``ePdfMarkupAnnotationTypeFileAttachmentAnnotation` → `ePtxPdfAnnots_MarkupAnnotationType_FileAttachment``ePdfMarkupAnnotationTypeFreeDrawingAnnotation` → `ePtxPdfAnnots_MarkupAnnotationType_InkAnnotation``ePdfMarkupAnnotationTypeFreeTextAnnotation` → `ePtxPdfAnnots_MarkupAnnotationType_FreeText``ePdfMarkupAnnotationTypeHighlightAnnotation` → `ePtxPdfAnnots_MarkupAnnotationType_Highlight``ePdfMarkupAnnotationTypeSquareAnnotation` → `ePtxPdfAnnots_MarkupAnnotationType_RectangleAnnotation``ePdfMarkupAnnotationTypeSquigglyAnnotation` → `ePtxPdfAnnots_MarkupAnnotationType_Squiggly``ePdfMarkupAnnotationTypeStampAnnotation` → `ePtxPdfAnnots_MarkupAnnotationType_Stamp``ePdfMarkupAnnotationTypeStickyNoteAnnotation` → `ePtxPdfAnnots_MarkupAnnotationType_StickyNote``ePdfMarkupAnnotationTypeStrikeThroughAnnotation` → `ePtxPdfAnnots_MarkupAnnotationType_StrikeThrough``ePdfMarkupAnnotationTypeTextInsertAnnotation` → `ePtxPdfAnnots_MarkupAnnotationType_TextInsert``ePdfMarkupAnnotationTypeTextMarkupAnnotation` → `ePtxPdfAnnots_MarkupAnnotationType_TextMarkup``ePdfMarkupAnnotationTypeTextStampAnnotation` → `ePtxPdfAnnots_MarkupAnnotationType_TextStamp``ePdfMarkupAnnotationTypeUnderlineAnnotation` → `ePtxPdfAnnots_MarkupAnnotationType_Underline`Renamed remaining enum values `ePdfMarkupAnnotationType...` → `ePtxPdfAnnots_MarkupAnnotationType_...`See [Annotations](C-interface.mdx#annotations). |
#### TPdfMarkupInfo
| [Class] `TPdfMarkupInfo` → `TPtxPdfAnnots_MarkupInfo` |
| ---------------------------------------------------------------------------- |
| Renamed related functions `PdfMarkupInfo...` → `PtxPdfAnnots_MarkupInfo_...` |
#### TPdfMarkupInfoList
| [Class] `TPdfMarkupInfoList` → `TPtxPdfAnnots_MarkupInfoList` |
| ---------------------------------------------------------------------------------------------- |
| Renamed remaining related functions `PdfMarkupInfoList...` → `PtxPdfAnnots_MarkupInfoList_...` |
#### TPdfPolyDrawingAnnotation
| `TPdfPolyDrawingAnnotation[class]` |
| -------------------------------------------------------- |
| Removed. See [Annotations](C-interface.mdx#annotations). |
#### TPdfPolyDrawingAnnotationType
| `TPdfPolyDrawingAnnotationType[enum]` → `TPtx_PolyDrawingAnnotationType` |
| ------------------------------------------------------------------------- |
| Removed. See [Annotations](C-interface.mdx#annotations). |
#### TPdfPolyLineAnnotation
| `TPdfPolyLineAnnotation[class]` → `TPtxPdfAnnots_PolyLineAnnotation` |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed base class to struct `TPtxPdfAnnots_DrawingAnnotation`.See [Annotations](C-interface.mdx#annotations).Renamed related functions `PdfPolyLineAnnotation...` → `PtxPdfAnnots_PolyLineAnnotation_...`New related function `TPtxPdfAnnots_PolyLineAnnotation* PtxPdfAnnots_PolyLineAnnotation_Create(` `TPtxPdf_Document* pTargetDocument,``TPtxPdfContent_Path* pPath,``TPtxPdfContent_Stroke* pStroke)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). See [TPdfDrawingAnnotation](#tpdfdrawingannotation) for inherited changes. |
#### TPdfPolygonAnnotation
| [Class] `TPdfPolygonAnnotation` → `TPtxPdfAnnots_PolygonAnnotation` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed base class to struct `TPtxPdfAnnots_DrawingAnnotation`. See [Annotations](C-interface.mdx#annotations). Renamed related functions `PdfPolygonAnnotation...` → `PtxPdfAnnots_PolygonAnnotation_...`New related function `TPtxPdfAnnots_PolygonAnnotation* PtxPdfAnnots_PolygonAnnotation_Create(` `TPtxPdf_Document* pTargetDocument,` `TPtxPdfContent_Path* pPath,` `TPtxPdfContent_Stroke* pStroke)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). See [TPdfDrawingAnnotation](#tpdfdrawingannotation) for inherited changes. |
#### TPdfShapeDrawingAnnotation
| [Class] `TPdfShapeDrawingAnnotation` |
| -------------------------------------------------------- |
| Removed. See [Annotations](C-interface.mdx#annotations). |
#### TPdfShapeDrawingAnnotationType
| [Enum.] `TPdfShapeDrawingAnnotationType` → `TPtx_ShapeDrawingAnnotationType` |
| ----------------------------------------------------------------------------- |
| Removed. See [Annotations](C-interface.mdx#annotations). |
#### TPdfSquareAnnotation
| [Class] `TPdfSquareAnnotation` → `TPtxPdfAnnots_RectangleAnnotation` |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed base class to struct `TPtxPdfAnnots_DrawingAnnotation`. See [Annotations](C-interface.mdx#annotations).New related function `TPtxPdfAnnots_PolylineAnnotation* PtxPdfAnnots_RectangleAnnotation_Create(` `TPtxPdf_Document* pTargetDocument,` `TPtxGeomReal_Rectangle* pBoundingBox,` `TPtxPdfContent_Stroke* pStroke,` `TPtxPdfContent_Fill* pFill)` See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods).New related function `TPtxPdfContent_Fill* PtxPdfAnnots_RectangleAnnotation_GetFill(``TPtxPdfAnnots_RectangleAnnotation*)`.See [TPdfDrawingAnnotation](#tpdfdrawingannotation) for inherited changes. |
#### TPdfSquigglyAnnotation
| [Class] `TPdfSquigglyAnnotation` → `TPtxPdfAnnots_Squiggly` |
| ------------------------------------------------------------------------------ |
| See [TPdfHighlightAnnotation](#tpdfhighlightannotation) for inherited changes. |
#### TPdfStampAnnotation
| [Class] `TPdfStampAnnotation` → `TPtxPdfAnnots_Stamp` |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related functions `PdfStampAnnotation...` → `PtxPdfAnnots_Stamp_...` See [TPdfMarkupAnnotation](#tpdfmarkupannotation) for inherited changes. |
#### TPdfStampAnnotationType
| [Enum.] `TPdfStampAnnotationType` → `TPtxPdfAnnots_StampType` |
| -------------------------------------------------------------------------------- |
| Renamed enum values `ePdfStampAnnotationType...` → `ePtxPdfAnnots_StampType_...` |
#### TPdfStickyNoteAnnotation
| [Class] `TPdfStickyNoteAnnotation` → `TPtxPdfAnnots_StickyNote` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related functions `PdfStickyNoteAnnotation...` → `PtxPdfAnnots_StickyNote_...`New related function `TPtxPdfAnnots_StickyNote* PtxPdfAnnots_StickyNote_Create(` `TPtxPdf_Document* pTargetDocument,``TPtxGeomReal_Point* pTopleft,`,br/`const char* szContent,` `TPtxPdfContent_Paint*pPaint)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). See [TPdfMarkupAnnotation](#tpdfmarkupannotation) for inherited changes. |
#### TPdfStrikeThroughAnnotation
| [Class] `TPdfStrikeThroughAnnotation` → `TPtxPdfAnnots_StrikeThrough` |
| -------------------------------------------------------------------------------- |
| See [TPdfTextMarkupAnnotation](#tpdftextmarkupannotation) for inherited changes. |
#### TPdfTextInsertAnnotation
| [Class] `TPdfTextInsertAnnotation` → `TPtxPdfAnnots_TextInsert` |
| -------------------------------------------------------------------------------- |
| See [TPdfTextMarkupAnnotation](#tpdftextmarkupannotation) for inherited changes. |
#### TPdfTextMarkupAnnotation
| [Class] `TPdfTextMarkupAnnotation` → `TPtxPdfAnnots_TextMarkup` |
| ------------------------------------------------------------------------ |
| See [TPdfMarkupAnnotation](#tpdfmarkupannotation) for inherited changes. |
#### TPdfTextMarkupAnnotationType
| [Enum.] `TPdfTextMarkupAnnotationType` → `TPtxPdfAnnots_TextMarkupType` |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed enum values: `ePdfTextMarkupAnnotationTypeHighlightAnnotation` → `ePtxPdfAnnots_TextMarkupType_Highlight` `ePdfTextMarkupAnnotationTypeSquigglyAnnotation` → `ePtxPdfAnnots_TextMarkupType_Squiggly` `ePdfTextMarkupAnnotationTypeStrikeThroughAnnotation` → `ePtxPdfAnnots_TextMarkupType_StrikeThrough` `ePdfTextMarkupAnnotationTypeTextInsertAnnotation` → `ePtxPdfAnnots_TextMarkupType_TextInsert` `ePdfTextMarkupAnnotationTypeTextMarkupAnnotation` → `ePtxPdfAnnots_TextMarkupType_TextMarkup` `ePdfTextMarkupAnnotationTypeUnderlineAnnotation` → `ePtxPdfAnnots_TextMarkupType_Underline` |
#### TPdfTextStampAnnotation
| [Class] `TPdfTextStampAnnotation` → `TPtxPdfAnnots_TextStamp` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| New related function `TPtxPdfAnnots_TextStamp* PtxPdfAnnots_TextStamp_Create(` `TPtxPdf_Document* pTargetDocument,` `TPtxGeomReal_Point* pTopleft,` `const double* pHeight,` `TPtxPdfAnnots_TextStampTypeiType,` `const char*szContent)` See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods).Renamed related functions `PdfTextStampAnnotation...` → `PtxPdfAnnots_TextStamp_...` See [TPdfStampAnnotation](#tpdfstampannotation) for inherited changes. |
#### TPdfTextStampType
| [Enum.] `TPdfTextStampType` → `TPtxPdfAnnots_TextStampType` |
| ------------------------------------------------------------------------------ |
| Renamed enum values `ePdfTextStampType...` → `ePtxPdfAnnots_TextStampType_...` |
#### TPdfUnderlineAnnotation
| [Class] `TPdfUnderlineAnnotation` → `TPtxPdfAnnots_Underline` |
| -------------------------------------------------------------------------------- |
| See [TPdfTextMarkupAnnotation](#tpdftextmarkupannotation) for inherited changes. |
### Prefix PtxPdfContent
#### TPdfBlendMode
| [Enum.] `TPdfBlendMode` → `TPtxPdfContent_BlendMode` |
| ----------------------------------------------------------------------- |
| Renamed enum values `ePdfBlendMode...` → `ePtxPdfContent_BlendMode_...` |
#### TPtxPdfContent_CalibratedGrayColorSpace
| [Class] `TPtxPdfContent_CalibratedGrayColorSpace` |
| ---------------------------------------------------------------------------------------------------- |
| Extends `TPtxPdfContent_ColorSpace`. See [Color space classes](./C-interface.mdx#color-space-classes). |
#### TPtxPdfContent_CalibratedRgbColorSpace
| [Class] `TPtxPdfContent_CalibratedRgbColorSpace` |
| ---------------------------------------------------------------------------------------------------- |
| Extends `TPtxPdfContent_ColorSpace`. See [Color space classes](./C-interface.mdx#color-space-classes). |
#### TPtxPdfContent_CalibratedCmykColorSpace
| [Class] `TPtxPdfContent_CalibratedCmykColorSpace` |
| ---------------------------------------------------------------------------------------------------- |
| Extends `TPtxPdfContent_ColorSpace`. See [Color space classes](./C-interface.mdx#color-space-classes). |
#### TPdfColorSpace
| [Class] `TPdfColorSpace` → `TPtxPdfContent_ColorSpace` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related function `PdfColorSpaceGetComponents` → `PtxPdfContent_ColorSpace_GetComponentCount`.Renamed related functions `PdfColorSpace...` → `PtxPdfContent_ColorSpace_...`Removed related function `PdfColorSpaceGetName`.New related function `TPtxPdfContent_ColorSpace* PtxPdfContent_ColorSpace_CreateProcessColorSpace(``TPtxPdf_Document* pTargetDocument,` `TPtxPdfContent_ProcessColorSpaceTypeiType)`New related function `TPtxPdfContent_ColorSpace* PtxPdfContent_ColorSpace_Copy(` `TPtxPdf_Document* pTargetDocument,` `TPtxPdfContent_ColorSpaceiColorSpace)` See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). See [Color space classes](./C-interface.mdx#color-space-classes). |
#### TPdfColorSpaceType
| [Enum.] `TPdfColorSpaceType` → `TPdfContent_ColorSpaceType` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| This enum now reflects the class hierarchy of classes derived from `TPtxPdfContent_ColorSpace`. See [Color space classes](./C-interface.mdx#color-space-classes).Removed enum value `ePdfColorSpaceDeviceN`.Renamed enum values:`ePdfColorSpaceDeviceGray` → `ePtxPdfContent_ColorSpaceType_DeviceGrayColorSpace``ePdfColorSpaceDeviceRGB` → `ePtxPdfContent_ColorSpaceType_DeviceRgbColorSpace``ePdfColorSpaceDeviceCMYK` → `ePtxPdfContent_ColorSpaceType_DeviceCmykColorSpace``ePdfColorSpaceCalGray` → `ePtxPdfContent_ColorSpaceType_CalibratedGrayColorSpace``ePdfColorSpaceCalRGB` → `ePtxPdfContent_ColorSpaceType_CalibratedRgbColorSpace``ePdfColorSpaceLab` → `ePtxPdfContent_ColorSpaceType_LabColorSpace``ePdfColorSpaceICCBased` → `ePtxPdfContent_ColorSpaceType_IccBasedColorSpace``ePdfColorSpaceIndexed` → `ePtxPdfContent_ColorSpaceType_IndexedColorSpace``ePdfColorSpaceSeparation` → `ePtxPdfContent_ColorSpaceType_SeparationColorSpace``ePdfColorSpaceNChannel` → `ePtxPdfContent_ColorSpaceType_NChannelColorSpace`New enum value `ePtxPdfContent_ColorSpaceType_ColorSpace` |
#### TPdfContent
| [Class] `TPdfContent` → `TPtxPdfContent_Content` |
| ------------------------------------------------- |
#### TPdfContentElement
| [Class] `TPdfContentElement` → `TPtxPdfContent_ContentElement` |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed related function `TPdfTransformation* PdfContentElementGetTransform(``TPdfContentElement*)` → `BOOL PtxPdfContent_ContentElement_GetTransform(` `TPtxPdfContent_ContentElement*,` `TPtxGeomReal_AffineTransform* pTransform)`SeeElements changed to class or struct.New related function `TPtxPdfContent_Contentelement* PtxPdfContent_ContentElement_Copy(` `TPtxPdf_Document *pTargetDocument,` `TPtxPdfContent_ContentElement* pContentElement)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). |
#### TPdfContentElementType
| [Enum.] `TPdfContentElementType` → `TPtxPdfContent_ContentElementType` |
| ----------------------------------------------------------------------------------------- |
| Renamed enum values `ePdfContentElementType...` → `ePtxPdfContent_ContentElementType_...` |
#### TPdfContentExtractor
| [Class] `TPdfContentExtractor` → `TPtxPdfContent_ContentExtractor` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related function `PdfNewContentExtractor` → `PtxPdfContent_ContentExtractor_New`. See Constructors.Renamed remaining related functions `PdfContentExtractor...` → `PtxPdfContent_ContentExtractor_...` |
#### TPdfContentGenerator
| [Class] `TPdfContentGenerator` → `TPtxPdfContent_ContentGenerator` |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed related function `BOOL PdfContentGeneratorPaintPath(` `TPdfContentGenerator*,` `TPdfPath* pPath,` `TPdfPaint* pFill,` `TPdfStrokeParams* pStroke,` `BOOL bIntersectClipping)` → `BOOL PtxPdfContent_ContentGenerator_PaintPath(` `TPtxPdfContent_ContentGenerator*,` `TPtxPdfContent_Path* pPath,``TPtxPdfContent_Fill* pFill,``TPtxPdfContent_Stroke* pStroke)` See [Separate inside rule from path](./C-interface.mdx#separate-inside-rule-from-path) and [Path and text clipping operations](C-interface.mdx#path-and-text-clipping-operations).Changed behavior of related functions `PdfContentGeneratorPaintImage` → `PtxPdfContent_ContentGenerator_PaintImage` and `PdfContentGeneratorPaintImageMask` → `PtxPdfContent_ContentGenerator_PaintImageMask`: Value `NULL` for third argument of type `TPdfRectangle*` → `TPtxGeomReal_Rectangle*` is not supported anymore.Renamed related function `PdfNewContentGenerator` → `PtxPdfContent_ContentGenerator_New`. See [Constructors](C-interface.mdx#constructors).Renamed remaining related functions `PdfContentGenerator...` → `PtxPdfContent_ContentGenerator_...`New related function `BOOL PtxPdfContent_ContentGenerator_ClipWithPath(``TPtxPdfContent_ContentGenerator*,``TPtxPdfContent_Path* pPath,``TPtxPdfContent_InsideRuleiInsideRule)`See [Separate inside rule from path](./C-interface.mdx#separate-inside-rule-from-path) and [Path and text clipping operations](C-interface.mdx#path-and-text-clipping-operations).New related function`BOOL PtxPdfContent_ContentGenerator_ClipWithText(``TPtxPdfContent_ContentGenerator*,``TPtxPdfContent_Text* pText)`See [Path and text clipping operations](C-interface.mdx#path-and-text-clipping-operations).New related function`BOOL PtxPdfContent_ContentGenerator_Close(``TPtxPdfContent_ContentGenerator*)`See [Closing and releasing](./C-interface.mdx#closing-and-releasing). |
#### TPdfDeviceColorSpaceType
| [Enum.] `TPdfDeviceColorSpaceType` → `TPtxPdfContent_ProcessColorSpaceType` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Renamed enum value `ePdfDeviceColorSpaceTypeRGB` → `ePtxPdfContent_ProcessColorSpaceType_Rgb`.Renamed enum value `ePdfDeviceColorSpaceTypeCMYK` → `ePtxPdfContent_ProcessColorSpaceType_Cmyk`.Renamed remaining enum values `ePdfDeviceColorSpaceType...` → `ePtxPdfContent_ProcessColorSpaceType_...` |
#### TPtxPdfContent_DeviceGrayColorSpace
| [Class] `TPtxPdfContent_DeviceGrayColorSpace` |
| ---------------------------------------------------------------------------------------------------- |
| Extends `TPtxPdfContent_ColorSpace`. See [Color space classes](./C-interface.mdx#color-space-classes). |
#### TPtxPdfContent_DeviceCmykColorSpace
| [Class] `TPtxPdfContent_DeviceCmykColorSpace` |
| ---------------------------------------------------------------------------------------------------- |
| Extends `TPtxPdfContent_ColorSpace`. See [Color space classes](./C-interface.mdx#color-space-classes). |
#### TPtxPdfContent_DeviceRgbColorSpace
| [Class] `TPtxPdfContent_DeviceRgbColorSpace` |
| ---------------------------------------------------------------------------------------------------- |
| Extends `TPtxPdfContent_ColorSpace`. See [Color space classes](./C-interface.mdx#color-space-classes). |
#### TPdfFillParams
| [Struct → class] `TPdfFillParams` → `TPtxPdfContent_Fill` |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed type from “struct”to“class”. See [Elements changed to class or struct](C-interface.mdx#elements-changed-to-class-or-struct).New related function `TPtxPdfContent_Fill* PtxPdfContent_Fill_New(` `TPtxPdfContent_Paint* pPaint)`.See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods) and [Constructors](C-interface.mdx#constructors).New related functions `TPtxPdfContent_Fill PtxPdfContent_Fill_GetPaint(``TPtxPdfContent_Fill*)` `BOOL PtxPdfContent_Fill_SetPaint(` `TPtxPdfContent_Fill*,``TPtxPdfContent_FillpPaint)`.New related functions `TPtxPdfContent_Fill PtxPdfContent_Fill_GetInsideRule(` TPtxPdfContent_Fill*)``BOOL PtxPdfContent_Fill_SetInsideRule(` `TPtxPdfContent_Fill*,``TPtxPdfContent_FilliInsideRule)`. See [Separate inside rule from path](./C-interface.mdx#separate-inside-rule-from-path). See [Elements changed to class or struct](C-interface.mdx#elements-changed-to-class-or-struct). |
#### TPdfFont
| [Class] `TPdfFont` → `TPtxPdfContent_Font` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related function `PdfFontGetCharWidth` → `PtxPdfContent_Font_GetCharacterWidth`.Renamed remaining related functions `PdfFont...` → `PtxPdfContent_Font_...`New related function `TPtxPdfContent_Font* PtxPdfContent_Font_Create(` `TPtxPdf_Document* pTargetDocument,``TPtxSys_StreamDescriptor* pStream,` `BOOL bEmbedded)` See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods).New related function `TPtxPdfContent_Font* PtxPdfContent_Font_CreateFromSystem(` `TPtxPdf_Document* pTargetDocument,` `const char* szFamily,` `const char* szStyle,` `BOOL bEmbedded)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). |
#### TPdfGroup
| [Class] `TPdfGroup` → `TPtxPdfContent_Group` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related functions `PdfGroup...` → `PtxPdfContent_Group_...`New related function`TPtxPdfContent_Group* PtxPdfContent_Group_Create(``TPtxPdf_Document* pTargetDocument,``TPtxGeomReal_Size* pSize)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods).New related function `TPtxPdfContent_Group* PtxPdfContent_Group_CreateFromPage(``TPtxPdf_Document* pTargetDocument,``TPtxPdf_Page* pPage,``TPtxPdf_PageCopyOptions* pCopyOptions)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). |
#### TPdfGroupElement
| [Class] `TPdfGroupElement` → `TPtxPdfContent_GroupElement` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related functions `PdfGroupElement...` → `PtxPdfContent_GroupElement_...`New related function`TPtxPdfContent_GroupElement* PtxPdfContent_GroupElement_CopyWithoutContent(``TPtxPdf_Document* pTargetDocument,``TPtxPdfContent_GroupElement* pGroupElement)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). |
See [TPdfContentElement](#tpdfcontentelement) for inherited changes.
#### TPtxPdfContent_IccBasedColorSpace
| [Class] `TPtxPdfContent_IccBasedColorSpace` |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends `TPtxPdfContent_ColorSpace`. Related function `TPtxPdfContent_IccBasedColorSpace* PtxPdfContent_IccBasedColorSpace_Create(``TPtxPdf_Document* pTargetDocument,``TPtxSys_StreamDescriptor* pProfile)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). See [Color space classes](./C-interface.mdx#color-space-classes). |
#### TPdfImage
| [Class] `TPdfImage` → `TPtxPdfContent_Image` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed related function `PdfImageGetWidth`. Replaced by new related function `PtxPdfContent_Image_GetSize`.Removed related function `PdfImageGetHeight`. Replaced by new related function `PtxPdfContent_Image_GetSize`.Renamed remaining related functions `PdfImage...` → `PtxPdfContent_Image_...`New related function `TPtxPdfContent_Image* PtxPdfContent_Image_Create(``TPtxPdf_Document* pTargetDocument,``TPtxSys_StreamDescriptor* pStream)` See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods).New related function `BOOL PtxPdfContent_Image_GetSize(` `TPtxPdfContent_Image*,``TPtxGeomReal_Size* pSize)`.See [Image size and image mask size](C-interface.mdx#image-size-and-image-mask-size). |
#### TPdfImageElement
| [Class] `TPdfImageElement` → `TPtxPdfContent_ImageElement` |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related functions `PdfImageElement...` → `PtxPdfContent_ImageElement_...`See [TPdfContentElement](#tpdfcontentelement) for inherited changes. |
#### TPdfImageMask
| [Class] `TPdfImageMask` → `TPtxPdfContent_ImageMask` |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed related function `PdfImageMaskGetWidth`. Replaced by new related function `PtxPdfContent_ImageMask_GetSize`.Removed related function `PdfImageMaskGetHeight`. Replaced by new related function `PtxPdfContent_ImageMask_GetSize`.New related function `TPtxPdfContent_ImageMask* PtxPdfContent_ImageMask_Create(``TPtxPdf_Document* pTargetDocument,``TPtxSys_StreamDescriptor*pStream)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods).New related function `BOOL PtxPdfContent_ImageMask_GetSize(``TPtxPdfContent_ImageMask*,``TPtxGeomReal_Size* pSize)`. See [Image size and image mask size](C-interface.mdx#image-size-and-image-mask-size). |
#### TPdfImageMaskElement
| [Class] `TPdfImageMaskElement` → `TPtxPdfContent_ImageMaskElement` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Renamed related functions `PdfImageMaskElement...` → `PtxPdfContent_ImageMaskElement_...`See [TPdfContentElement](#tpdfcontentelement) for inherited changes. |
#### TPtxPdfContent_IndexedColorSpace
| [Class] `TPtxPdfContent_IndexedColorSpace` |
| ------------------------------------------ |
| Extends `TPtxPdfContent_ColorSpace`.See [Color space classes](./C-interface.mdx#color-space-classes).
#### TPdfInsideRule
| [Enum.] `TPdfInsideRule` → `TPtxPdfContent_InsideRule` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed enum values:`ePdfRuleNonzeroWindingNumber` → `ePdfContent_InsideRule_NonzeroWindingNumber``ePdfRuleEvenOdd` → `ePdfContent_InsideRule_EvenOdd` |
#### TPtxPdfContent_LabColorSpace
| [Class] `TPtxPdfContent_LabColorSpace` |
| ---------------------------------------------------------------------------------------------------- |
| Extends `TPtxPdfContent_ColorSpace`. See [Color space classes](./C-interface.mdx#color-space-classes). |
#### TPdfLineCapStyle
| [Enum.] `TPdfLineCapStyle` → `TPtxPdfContent_LineCapStyle` |
| ----------------------------------------------------------------- |
| Renamed enum values`ePdfCap...`→`ePtxPdfContent*LineCapStyle*...` |
#### TPdfLineJoinStyle
| [Enum.] `TPdfLineJoinStyle` → `TPtxPdfContent_LineJoinStyle` |
| ------------------------------------------------------------------- |
| Renamed enum values`ePdfJoin...`→`ePtxPdfContent*LineJoinStyle*...` |
#### TPtxPdfContent_NChannelColorSpace
| [Class] `TPtxPdfContent_NChannelColorSpace` |
| ---------------------------------------------------------------------------------------------------- |
| Extends `TPtxPdfContent_ColorSpace`. See [Color space classes](./C-interface.mdx#color-space-classes). |
#### TPdfPaint
| [Class] `TPdfPaint` → `TPtxPdfContent_Paint` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related functions `PdfPaint...` → `PtxPdfContent_Paint_...`Changed related function `BOOL PdfPaintGetTransparency(``TPdfPaint*,``TPdfTransparencyParams* pTransparency)` → `TPtxPdfContent_Transparency* PtxPdfContent_Paint_GetTransparency(``TPtxPdfContent_Paint*)` See [Elements changed to class or struct](C-interface.mdx#elements-changed-to-class-or-struct).New related function `TPtxPdfContent_Paint* PtxPdfContent_Paint_Create(``TPtxPdf_Document* pTargetDocument,``TPtxPdfContent_ColorSpace* pColorSpace,``const double* pColor,``size_tnColors,``TPtxPdfContent_Transparency* pTransparency)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods) and [Unified paint creation](./C-interface.mdx#unified-paint-creation). |
#### TPdfPath
| [Class] `TPdfPath` → `TPtxPdfContent_Path` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed related function `TPdfPath* PdfNewPath(TPdfFillRuleiRule)` → `TPtxPdfContent_Path* PtxPdfContent_Path_New()`. See [Constructors](C-interface.mdx#constructors) and [Separate inside rule from path](./C-interface.mdx#separate-inside-rule-from-path).Renamed related functions `PdfPath...` → `PtxPdfContent_Path_...` |
#### TPdfPathElement
| [Class] `TPdfPathElement` → `TPtxPdfContent_PathElement` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related functions `PdfPathElement...` → `PtxPdfContent_PathElement_...`Changed related function `BOOL PdfPathElementGetFill(` `TPdfPathElement*,` `TPdfFillParams*pFill)` → `TPtxPdfContent_Fill* PtxPdfContent_PathElement_GetFill(``TPtxPdfContent_PathElement*)`See [Elements changed to class or struct](C-interface.mdx#elements-changed-to-class-or-struct).Changed related function `BOOL PdfPathElementGetStroke(``TPdfPathElement*,``TPdfStrokeParams* pStroke)` → `TPtxPdfContent_Stroke* PtxPdfContent_PathElement_GetStroke(``TPtxPdfContent_PathElement*)` See [Elements changed to class or struct](C-interface.mdx#elements-changed-to-class-or-struct). See [TPdfContentElement](#tpdfcontentelement) for inherited changes. |
#### TPdfPathGenerator
| [Class] `TPdfPathGenerator` → `TPtxPdfContent_PathGenerator` |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related function `PdfNewPathGenerator` → `PtxPdfContent_PathGenerator_New`. See [Constructors](C-interface.mdx#constructors).Renamed remaining related functions `PdfPathGenerator...` → `PtxPdfContent_PathGenerator_...` |
#### TPtxPdfContent_SeparationColorSpace
| [Class] `TPtxPdfContent_SeparationColorSpace` |
| ---------------------------------------------------------------------------------------------------- |
| Extends `TPtxPdfContent_ColorSpace`. See [Color space classes](./C-interface.mdx#color-space-classes). |
#### TPdfShadingElement
| [Class]`TPdfShadingElement` → `TPtxPdfContent_ShadingElement` |
| -------------------------------------------------------------------- |
| See [TPdfContentElement](#tpdfcontentelement) for inherited changes. |
#### TPdfStrokeParams
| [Struct → class] `TPdfStrokeParams` → `TPtxPdfContent_Stroke` |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed type from “struct” to “class”. See [Elements changed to class or struct](C-interface.mdx#elements-changed-to-class-or-struct).New related function `TPtxPdfContent_Stroke* PtxPdfContent_Stroke_New(` `TPtxPdfContent_Paint* pPaint,` `double dLineWidth)`. See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods) and [Constructors](C-interface.mdx#constructors).New related functions`TPtxPdfContent_Paint* PtxPdfContent_Stroke_GetPaint(``TPtxPdfContent_Stroke*)``BOOL PtxPdfContent_Stroke_SetPaint(``TPtxPdfContent_Stroke*,``TPtxPdfContent_Paint* pPaint)`.New related functions`double PtxPdfContent_Stroke_GetLineWidth(` `TPtxPdfContent_Stroke*)` `BOOL PtxPdfContent_Stroke_SetLineWidth(``TPtxPdfContent_Stroke*,` `double dLineWidth)`.New related functions `TPtxPdfContent_LineCapStyle PtxPdfContent_Stroke_GetLineCapStyle(``TPtxPdfContent_Stroke*)``BOOL PtxPdfContent_Stroke_SetLineCapStyle(``TPtxPdfContent_Stroke*,` `TPtxPdfContent_LineCapStyle iLineCapStyle)`.New related functions`TPtxPdfContent_LineJoinStyle PtxPdfContent_Stroke_GetLineJoinStyle(``TPtxPdfContent_Stroke*)``BOOL PtxPdfContent_Stroke_SetLineJoinStyle(``TPtxPdfContent_Stroke*,``TPtxPdfContent_LineJoinStyle iLineJoinStyle)`.New related functions `double PtxPdfContent_Stroke_GetMiterLimit(``TPtxPdfContent_Stroke*)``BOOL PtxPdfContent_Stroke_SetMiterLimit(``TPtxPdfContent_Stroke*,` `double dMiterLimit)`.New related functions `size_t PtxPdfContent_Stroke_GetDashArray(` `TPtxPdfContent_Stroke*,` `double* pBuffer,` `size_t nBufferSize)``BOOL PtxPdfContent_Stroke_SetDashArray(``TPtxPdfContent_Stroke*,` `const double* pBuffer,``size_t nBufferSize)`.New related functions `double PtxPdfContent_Stroke_GetDashPhase(``TPtxPdfContent_Stroke*)``BOOL PtxPdfContent_Stroke_SetDashPhase(``TPtxPdfContent_Stroke*,``double dDashPhase)`. See [Elements changed to class or struct](C-interface.mdx#elements-changed-to-class-or-struct). |
#### TPdfText
| [Class] `TPdfText` → `TPtxPdfContent_Text` |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related functions `PdfText...` → `PtxPdfContent_Text_...`New related function `TPtxPdfContent_Text* PtxPdfContent_Text_Create(` `TPtxPdf_Document* pTargetDocument)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). |
#### TPdfTextElement
| [Class] `TPdfTextElement` → `TPtxPdfContent_TextElement` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Renamed related functions`PdfTextElement...`→`PtxPdfContent*TextElement*...` See [TPdfContentElement](#tpdfcontentelement) for inherited changes. |
#### TPdfTextFragment
| [Class] `TPdfTextFragment` → `TPtxPdfContent_TextFragment` |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related function `PdfTextFragmentGetUnicodeString` → `PtxPdfContent_TextFragment_GetText`.Changed related function `TPdfTransformation* PdfTextFragmentGetTransform(TPdfTextFragment*)` → `BOOL PtxPdfContent_TextFragment_GetTransform(``TPtxPdfContent_TextFragment*,``TPtxGeomReal_AffineTransform* pTransform)` See [Elements changed to class or struct](C-interface.mdx#elements-changed-to-class-or-struct).Changed related function `BOOL PdfTextFragmentGetFill(` `TPdfTextFragment*,``TPdfFillParams* pFill)` → `TPtxPdfContent_Fill* PtxPdfContent_TextFragment_GetFill(` `TPtxPdfContent_TextFragment*)` See [Elements changed to class or struct](C-interface.mdx#elements-changed-to-class-or-struct).Changed related function `BOOL PdfTextFragmentGetStroke(` `TPdfTextFragment*,` `TPdfStrokeParams*pStroke)` → `TPtxPdfContent_Stroke*` `PtxPdfContent_TextFragment_GetStroke(` `TPtxPdfContent_TextFragment*)`See [Elements changed to class or struct](C-interface.mdx#elements-changed-to-class-or-struct).Renamed remaining related functions `PdfTextFragment...` → `PtxPdfContent_TextFragment_...` |
#### TPdfTextGenerator
| [Class] `TPdfTextGenerator` → `TPtxPdfContent_TextGenerator` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Removed related function `PdfTextGeneratorSetRendering`. Replaced by related functions `PtxPdfContent_TextGenerator_SetFill` and `PtxPdfContent_TextGenerator_SetStroke`. See [Text generator](C-interface.mdx#text-generator).Renamed related function `PdfNewTextGenerator` → `PtxPdfContent_TextGenerator_New`. See [Constructors](C-interface.mdx#constructors).Renamed related function `PdfTextGeneratorSetCharSpacing` → `PtxPdfContent_TextGenerator_SetCharacterSpacing`. See [Renaming](C-interface.mdx#renaming).Renamed remaining related functions `PdfTextGenerator...` → `PtxPdfContent_TextGenerator_...`New related functions `TPtxPdfContent_Paint* PtxPdfContent_TextGenerator_GetFill(``TPtxPdfContent_TextGenerator*)``BOOL PtxPdfContent_TextGenerator_SetFill(``TPtxPdfContent_TextGenerator*,``TPtxPdfContent_Paint*pFill)`.New related functions `TPtxPdfContent_Stroke* PtxPdfContent_TextGenerator_GetStroke(``TPtxPdfContent_TextGenerator*)``BOOL PtxPdfContent_TextGenerator_SetStroke(``TPtxPdfContent_TextGenerator*,``TPtxPdfContent_Stroke* pStroke)`.New related function `BOOL PtxPdfContent_TextGenerator_Close(``TPtxPdfContent_TextGenerator*)`See [Closing and releasing](./C-interface.mdx#closing-and-releasing). |
#### TPdfTransparencyParams
| [Struct → Class] `TPdfTransparencyParams` → `TPtxPdfContent_Transparency` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed type from “struct” to “class”. See [Elements changed to class or struct](C-interface.mdx#elements-changed-to-class-or-struct).New related function `TPtxPdfContent_Transparency* PtxPdfContent_Transparency_New(doubledAlpha)`.New related functions `TPtxPdfContent_BlendMode PtxPdfContent_Transparency_GetBlendMode(``TPtxPdfContent_Transparency*)``BOOL PtxPdfContent_Transparency_SetBlendMode(``TPtxPdfContent_Transparency*,``TPtxPdfContent_BlendModeiBlendMode)`.New related functions `double PtxPdfContent_Transparency_GetAlpha(``TPtxPdfContent_Transparency*)``BOOL PtxPdfContent_Transparency_SetAlpha(``TPtxPdfContent_Transparency*,``double dAlpha)`.See [Elements changed to class or struct](C-interface.mdx#elements-changed-to-class-or-struct). |
#### TPdfUngroupingSet
| [Enum.] `TPdfUngroupingSet` → `TPtxPdfContent_UngroupingSelection` |
| -------------------------------------------------------------------------------------------------------- |
| Renamed enum values `ePdfUngroupingSet...` → `ePtxPdfContent_UngroupingSelection_...` |
### Prefix PtxPdfForms
#### TPdfCheckBoxField
| [Class] `TPdfCheckBoxField` → `TPtxPdfForms_CheckBox` |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related functions `PdfCheckBoxField...` → `PtxPdfForms_CheckBox_...`New related function `TPtxPdfForms_CheckBox* PtxPdfForms_CheckBox_Create(``TPtxPdf_Document* pTargetDocument)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). |
See `TPdfFormField` for inherited changes.
#### TPdfChoiceField
| [Class] `TPdfChoiceField` → `TPtxPdfForms_ChoiceField` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related functions `PdfChoiceField...` → `PtxPdfForms_ChoiceField_...` See [TPdfFormField](#tpdfformfield) for inherited changes. |
#### TPdfChoiceFieldType
| [Enum.] `TPdfChoiceFieldType` → `TPtxPdfForms_ChoiceFieldType` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed enum values:`ePdfChoiceFieldTypeComboBoxField` → `ePtxPdfForms_ChoiceFieldType_ComboBox``ePdfChoiceFieldTypeListBoxField` → `ePtxPdfForms_ChoiceFieldType_ListBox`Renamed enum values `ePdfChoiceFieldType...` → `ePtxPdfForms_ChoiceFieldType_...` |
#### TPdfChoiceItem
| [Class] `TPdfChoiceItem` → `TPtxPdfForms_ChoiceItem` |
| --------------------------------------------------------------------------- |
| Renamed related functions `PdfChoiceItem...` → `PtxPdfForms_ChoiceItem_...` |
#### TPdfChoiceItemList
| [Class] `TPdfChoiceItemList` → `TPtxPdfForms_ChoiceItemList` |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related function `PdfChoiceItemListAppend` → `PtxPdfForms_ChoiceItemList_Add`.Renamed remaining related functions `PdfChoiceItemList...` → `PtxPdfForms_ChoiceItemList_...` |
#### TPdfComboBoxField
| [Class] `TPdfComboBoxField` → `TPtxPdfForms_ComboBox` |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related functions `PdfComboBoxField...` → `PtxPdfForms_ComboBox_...`>New related function `TPtxPdfForms_ComboBox* PtxPdfForms_ComboBox_Create(``TPtxPdf_Document* pTargetDocument)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). See [TPdfChoiceField](#tpdfchoicefield) for inherited changes. |
#### TPdfCombTextField
| [Class] `TPdfCombTextField` → `TPtxPdfForms_CombTextField` |
| ----------------------------------------------------------- |
| Renamed related functions `PdfCombTextField...` → `PtxPdfForms_CombTextField_...` New related function `TPtxPdfForms_CombTextField* PtxPdfForms_CombTextField_Create(``TPtxPdf_Document* pTargetDocument,``intiMaxLength)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods).New related functions `int PtxPdfForms_CombTextField_GetMaxLength(``TPtxPdfForms_CombTextField*)``BOOL PtxPdfForms_CombTextField_SetMaxLength(``TPtxPdfForms_CombTextField*,``int iMaxLength)`. See [MaxLength in text fields](./C-interface.mdx#maxlength-in-text-fields). See [TPdfTextField](#tpdftextfield) for inherited changes.
#### TPdfFormField
| [Class] `TPdfFormField` → `TPtxPdfForms_Field` |
| ---------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related functions `PdfFormField...` → `PtxPdfForms_Field_...`See [TPdfFormFieldNode](#tpdfformfield) for inherited changes. |
#### TPtxPdfForms_FormFieldCopyStrategy
| [Enum.] `TPtxPdfForms_FormFieldCopyStrategy` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Values:`ePtxPdfForms_FormFieldCopyStrategy_Copy``ePtxPdfForms_FormFieldCopyStrategy_Flatten``ePtxPdfForms_FormFieldCopyStrategy_Remove``ePtxPdfForms_FormFieldCopyStrategy_Copy AndUpdateWidgets`Substitutes the removed `TPdfCopyOption`. See [Copy options](C-interface.mdx#copy-options). |
#### TPdfFormFieldType
| [Enum.] `TPdfFormFieldType` → `TPtxPdfForms_FieldType` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed enum values:`ePdfFormFieldTypeCheckBoxField` → `ePtxPdfForms_FieldType_CheckBox``ePdfFormFieldTypeComboBoxField` → `ePtxPdfForms_FieldType_ComboBox``ePdfFormFieldTypeFormField` → `ePtxPdfForms_FieldType_Field``ePdfFormFieldTypeListBoxField` → `ePtxPdfForms_FieldType_ListBox``ePdfFormFieldTypePushButtonField` → `ePtxPdfForms_FieldType_PushButton``ePdfFormFieldTypeRadioButtonField` → `ePtxPdfForms_FieldType_RadioButtonGroup`Renamed enum values `ePdfFormFieldType...` → `ePtxPdfForms_FieldType_...` |
#### TPdfFormFieldNode
| [Class] `TPdfFormFieldNode` → `TPtxPdfForms_FieldNode` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Renamed related functions `PdfFormFieldNode...` → `PtxPdfForms_FieldNode_...`New related function `TPtxPdfForms_FieldNode* PtxPdfForms_FieldNode_Copy(``TPtxPdf_Document* pTargetDocument,``TPtxPdfForms_FieldNode* pFieldNode)` See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). |
#### TPdfFormFieldNodeMap
| [Class] `TPdfFormFieldNodeMap` → `TPtxPdfForms_FieldNodeMap` |
| ----------------------------------------------------------------------------------- |
| Renamed related functions `PdfFormFieldNodeMap...` → `PtxPdfForms_FieldNodeMap_...` |
#### TPdfFormFieldNodeType
| [Enum.] `TPdfFormFieldNodeType` → `TPtxPdfForms_FieldNodeType` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed enum values:`ePdfFormFieldNodeTypeCheckBoxField` → `ePtxPdfForms_FieldNodeType_CheckBox``ePdfFormFieldNodeTypeComboBoxField` → `ePtxPdfForms_FieldNodeType_ComboBox``ePdfFormFieldNodeTypeFormField` → `ePtxPdfForms_FieldNodeType_Field``ePdfFormFieldNodeTypeFormFieldNode` → `ePtxPdfForms_FieldNodeType_FieldNode``ePdfFormFieldNodeTypeListBoxField` → `ePtxPdfForms_FieldNodeType_ListBox``ePdfFormFieldNodeTypePushButtonField` → `ePtxPdfForms_FieldNodeType_PushButton``ePdfFormFieldNodeTypeRadioButtonField` → `ePtxPdfForms_FieldNodeType_RadioButtonGroup`Renamed enum values `ePdfFormFieldNodeType...` → `ePtxPdfForms_FieldNodeType_...` |
#### TPdfGeneralTextField
| [Class] `TPdfGeneralTextField` → `TPtxPdfForms_GeneralTextField` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related functions `PdfGeneralTextField...` → `PtxPdfForms_GeneralTextField_...`New related function `TPtxPdfForms_GeneralTextField* PtxPdfForms_GeneralTextField_Create(``TPtxPdf_Document* pTargetDocument)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). New related functions `BOOL PtxPdfForms_GeneralTextField_GetMaxLength(``TPtxPdfForms_GeneralTextField*,``int* pMaxLength)``BOOL PtxPdfForms_GeneralTextField_SetMaxLength(``TPtxPdfForms_GeneralTextField*,``const int*pMaxLength)`.See [MaxLength in text fields](./C-interface.mdx#maxlength-in-text-fields). |
See [TPdfTextField](#tpdfcombtextfield) for inherited changes.
#### TPdfListBoxField
| [Class] `TPdfListBoxField` → `TPtxPdfForms_ListBox` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related functions `PdfListBoxField...` → `PtxPdfForms_ListBox_...`New related function `TPtxPdfForms_ListBox* PtxPdfForms_ListBox_Create(``TPtxPdf_Document* pTargetDocument)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). |
See [TPdfChoiceField](#tpdfchoicefield) for inherited changes.
#### TPdfPushButtonField
| [Class] `TPdfPushButtonField` → `TPtxPdfForms_PushButton` |
| ---------------------------------------------------------- |
#### TPdfRadioButton
| [Class] `TPdfRadioButton` → `TPtxPdfForms_RadioButton` |
| ----------------------------------------------------------------------------- |
| Renamed related functions `PdfRadioButton...` → `PtxPdfForms_RadioButton_...` |
#### TPdfRadioButtonField
| [Class] `TPdfRadioButtonField` → `TPtxPdfForms_RadioButtonGroup` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed related functions `PdfRadioButtonFieldGetCanToggleOff` and `PdfRadioButtonFieldSetCanToggleOff`.>Renamed remaining related functions `PdfRadioButtonField...` → `PtxPdfForms_RadioButtonGroup_...`New related function `TPtxPdfForms_RadioButtonGroup* PtxPdfForms_RadioButtonGroup_Create(``TPtxPdf_Document* pTargetDocument)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). See [TPdfFormField](#tpdfformfield) for inherited changes. |
#### TPdfRadioButtonList
| [Class] `TPdfRadioButtonList` → `TPtxPdfForms_RadioButtonList` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Renamed related function `PdfRadioButtonListAppend` → `PtxPdfForms_RadioButtonList_Add`.Renamed remaining related functions `PdfRadioButtonList...` → `PtxPdfForms_RadioButtonList_...` |
#### TPdfSignatureField
| [Class] `TPdfSignatureField` → `TPtxPdfForms_SignatureField` |
| ----------------------------------------------------------------------------------- |
| Renamed related functions `PdfSignatureField...` → `PtxPdfForms_SignatureField_...` |
#### TPdfSignatureFieldList
| [Class] `TPdfSignatureFieldList` → `TPtxPdfForms_SignatureFieldList` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Renamed related function `PdfSignatureFieldListAppend` → `PtxPdfForms_SignatureFieldList_Add`.Renamed remaining related functions `PdfSignatureFieldList...` → `PtxPdfForms_SignatureFieldList_...` |
#### TPdfSubForm
| [Class] `TPdfSubForm` → `TPtxPdfForms_SubForm` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related functions `PdfSubForm...` → `PtxPdfForms_SubForm_...`New related function `TPtxPdfForms_SubForm* PtxPdfForms_SubForm_Create(``TPtxPdf_Document* pTargetDocument)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). See [TPdfFormFieldNode](#tpdfformfieldnode) for inherited changes.` |
#### TPdfTextField
| [Class] `TPdfTextField` → `TPtxPdfForms_TextField` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed related functions `PdfTextFieldGetMaxLength` and `PdfTextFieldSetMaxLength`. See [MaxLength in text fields](./C-interface.mdx#maxlength-in-text-fields)Renamed related functions `PdfTextField...` → `PtxPdfForms_TextField_...` |
See [TPdfFormFieldNode](#tpdfformfieldnode) for inherited changes.
#### TPdfTextFieldType
| [Enum.] `TPdfTextFieldType` → `TPtxPdfForms_TextFieldType` |
| ----------------------------------------------------------------------------- |
| Renamed enum values `ePdfTextFieldType...` → `ePtxPdfForms_TextFieldType_...` |
#### TPdfWidget
| [Class] `TPdfWidget` → `TPtxPdfForms_Widget` |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed inheritance from class `TPdfAnnotation`. See [Annotations](C-interface.mdx#annotations).Duplicated related function `TPtxGeomReal_Rectangle* PtxPdfForms_Widget_GetBoundingBox(``TPtxPdfForms_Widget*)`from former base class `TPdfAnnotation`.Duplicated related function `BOOL PtxPdfForms_Widget_GetHidden(` `TPtxPdfForms_Widget*)`from former base class `TPdfAnnotation`.Duplicated related function `BOOL PtxPdfForms_Widget_GetNoPrint(``TPtxPdfForms_Widget*)`from former base class `TPdfAnnotation`. |
#### TPdfWidgetList
| [Class] `TPdfWidgetList` → `TPtxPdfForms_WidgetList` |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related function `PdfWidgetListAppend` → `PtxPdfForms_WidgetList_Add`.Renamed remaining related functions `PdfWidgetList...` → `PtxPdfForms_WidgetList_...` |
### Prefix PtxPdfNav
#### TPdfDestination
| [Class] `TPdfDestination` → `TPtxPdfNav_Destination` |
| --------------------------------------------------------------------------- |
| Renamed related functions `PdfDestination...` → `PtxPdfNav_Destination_...` |
#### TPdfDestinationType
| [Enum.] `TPdfDestinationType` → `TPtxPdfNav_DestinationType` |
| ------------------------------------------------------------------------------- |
| Renamed enum values `ePdfDestinationType...` → `ePtxPdfNav_DestinationType_...` |
#### TPdfDirectDestination
| [Class] `TPdfDirectDestination` → `TPtxPdfNav_DirectDestination` |
| --------------------------------------------------------------------------------------- |
| Renamed related functions `PdfDirectDestination...` → `PtxPdfNav_DirectDestination_...` |
See [TPdfDestination](#tpdfdestination) for inherited changes.
#### TPdfDirectDestinationType
| [Enum.] `TPdfDirectDestinationType` → `TPtxPdfNav_DirectDestinationType` |
| ------------------------------------------------------------------------------------------- |
| Renamed enum values `ePdfDirectDestinationType...` → `ePtxPdfNav_DirectDestinationType_...` |
#### TPdfEmbeddedPdfLink
| [Class] `TPdfEmbeddedPdfLink` → `TPtxPdfNav_EmbeddedPdfLink` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed related function `PdfNewEmbeddedPdfLink`. See [Constructors](C-interface.mdx#constructors).Renamed related functions `PdfEmbeddedPdfLink...` → `PtxPdfNav_EmbeddedPdfLink_...`New related function `TPtxPdfNav_EmbeddedPdfLink* PtxPdfNav_EmbeddedPdfLink_Create(``TPtxPdf_Document* pTargetDocument,``TPtxGeomReal_Rectangle* pBoundingBox,``TPtxPdf_FileReference* pFileReference)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). See [TPdfLink](#tpdflink) for inherited changes. |
#### TPdfFitHeightDestination
| [Class] `TPdfFitHeightDestination` → `TPtxPdfNav_FitHeightDestination` |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed related function `PdfNewFitHeightDestination`. See [Constructors](C-interface.mdx#constructors).Renamed remaining related functions `PdfFitHeightDestination...` → `PtxPdfNav_FitHeightDestination_...`New related function `TPtxPdfNav_FitHeightDestination* PtxPdfNav_FitHeightDestination_Create(``TPtxPdf_Document* pTargetDocument,``TPtxPdf_Page* pPage,``BOOL bFitActualContent)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). See [TPdfDirectDestination](#tpdfdirectdestination) for inherited changes. |
#### TPdfFitPageDestination
| [Class] `TPdfFitPageDestination` → `TPtxPdfNav_FitPageDestination` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed related function `PdfNewFitPageDestination`. See [Constructors].Renamed remaining related functions `PdfFitPageDestination...` → `PtxPdfNav_FitPageDestination_...`New related function`TPtxPdfNav_FitPageDestination* PtxPdfNav_FitPageDestination_Create(``TPtxPdf_Document* pTargetDocument, ``TPtxPdf_Page* pPage,``BOOL bFitActualContent)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). |
See [TPdfDirectDestination](#tpdfdirectdestination) for inherited changes.
#### TPdfFitRectangleDestination
| [Class] `TPdfFitRectangleDestination` → `TPtxPdfNav_FitRectangleDestination` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed related function `PdfNewFitRectangleDestination`. See [Constructors](C-interface.mdx#constructors). Renamed remaining related functions `PdfFitRectangleDestination...` → `PtxPdfNav_FitRectangleDestination_...`New related function `TPtxPdfNav_FitRectangleDestination* PtxPdfNav_FitRectangleDestination_Create(` `TPtxPdf_Document* pTargetDocument,``TPtxPdf_Page* pPage,``TPtxGeomReal_Rectangle* pRectangle)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). |
See [TPdfDirectDestination](#tpdfdirectdestination) for inherited changes.
#### TPdfFitWidthDestination
| [Class] `TPdfFitWidthDestination` → `TPtxPdfNav_FitWidthDestination` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed related function `PdfNewFitWidthDestination`. See [Constructors](C-interface.mdx#constructors).Renamed remaining related functions `PdfFitWidthDestination...` → `PtxPdfNav_FitWidthDestination_...`New related function `TPtxPdfNav_FitWidthDestination* PtxPdfNav_FitWidthDestination_Create(``TPtxPdf_Document* pTargetDocument,``TPtxPdf_Page* pPage,``BOOL bFitActualContent)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). |
See [TPdfDirectDestination](#tpdfdirectdestination) for inherited changes.
#### TPdfInternalLink
| [Class] `TPdfInternalLink` → `TPtxPdfNav_InternalLink` |
| ------------------------------------------------------------------------------ | ------------------------------------------------ |
| Renamed related functions `PdfInternalLink...` → `PtxPdfNav_InternalLink_...` | See [TPdfLink](#tpdflink) for inherited changes. |
#### TPdfLink
| [Class] `TPdfLink` → `TPtxPdfNav_Link` |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed inheritance from class `TPdfAnnotation`. See [Annotations](C-interface.mdx#annotations).Renamed related functions `PdfLink...` → `PtxPdfNav_Link_...`New related function `TPtxPdfNav_Link* PtxPdfNav_Link_Copy(` `TPtxPdf_Document* pTargetDocument,``TPtxPdfNav_Link* pLink)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). Duplicated related function `TPtxGeomReal_Rectangle* PtxPdfNav_Link_GetBoundingBox(``TPtxPdfNav_Link*)` from former base class `TPdfAnnotation`.Duplicated related function `BOOL PtxPdfNav_Link_GetHidden(``TPtxPdfNav_Link*)`from former base class `TPdfAnnotation`.Duplicated related function `BOOL PtxPdfNav_Link_GetNoPrint(``TPtxPdfNav_Link*)`from former base class `TPdfAnnotation`. |
#### TPtxPdfNav_LinkList
| [Class] `TPtxPdfNav_LinkList` |
| --------------------------------------------------- |
| A list that contains [TPdfLink](#tpdflink) objects. |
#### TPdfLinkType
| [Enum.] `TPdfLinkType` → `TPtxPdfNav_LinkType` |
| ----------------------------------------------------------------- |
| Renamed enum values `ePdfLinkType...` → `ePtxPdfNav_LinkType_...` |
#### TPdfLocationZoomDestination
| [Class] `TPdfLocationZoomDestination` → `TPtxPdfNav_LocationZoomDestination` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed related function `PdfNewLocationZoomDestination`. See [Constructors](C-interface.mdx#constructors).Renamed remaining related functions `PdfLocationZoomDestination...` → `PtxPdfNav_LocationZoomDestination_...`New related function`TPtxPdfNav_ZoomDestination* PtxPdfNav_LocationZoomDestination_Create(``TPtxPdf_Document* pTargetDocument,``TPtxPdf_Page* pPage,``const double* pLeft,``const double* pTop,``const double* pZoom)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). |
See [TPdfDirectDestination](#tpdfdirectdestination) for inherited changes.
#### TPdfNamedDestination
| [Class] `TPdfNamedDestination` → `TPtxPdfNav_NamedDestination` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Renamed related functions `PdfNamedDestination...` → `PtxPdfNav_NamedDestination_...`New related function `TPtxPdfNav_NamedDestination* PtxPdfNav_NamedDestination_Create(``TPtxPdf_Document* pTargetDocument,``const char* szName,``TPtxPdfNav_DirectDestination* pTarget)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). |
See [TPdfDestination](#tpdfdestination) for inherited changes.
#### TPtxPdfNav_NamedDestinationCopyStrategy
| [Enum.] `TPtxPdfNav_NamedDestinationCopyStrategy` |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Values:`ePtxPdfNav_NamedDestinationCopyStrategy_Copy``ePtxPdfNav_NamedDestinationCopyStrategy_Resolve`Substitutes the removed `TPdfCopyOption`. See [Copy options](C-interface.mdx#copy-options). |
#### TPtxPdfNav_OutlineCopyOptions
| [Class] `TPtxPdfNav_OutlineCopyOptions` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Related function `TPtxPdfNav_OutlineCopyOptions* PtxPdfNav_OutlineCopyOptions_New()`Related functions `TPtxPdfNav_NamedDestinationCopyStrategy PtxPdfNav_OutlineCopyOptions_GetNamedDestinations(``TPtxPdfNav_OutlineCopyOptions*)``BOOL PtxPdfNav_OutlineCopyOptions_SetNamedDestinations(``TPtxPdfNav_OutlineCopyOptions*,``TPtxPdfNav_NamedDestinationCopyStrategyiNamedDestinations)`Default: `ePtxPdfNav_NamedDestinationCopyStrategy_Copy`Related functions`BOOL PtxPdfNav_OutlineCopyOptions_GetCopyLogicalStructure(``TPtxPdfNav_OutlineCopyOptions*)``BOOL PtxPdfNav_OutlineCopyOptions_SetCopyLogicalStructure(``TPtxPdfNav_OutlineCopyOptions*,``BOOL bCopyLogicalStructure)`Default: `TRUE` Substitutes the removed `TPdfCopyOption`. See [Copy options](C-interface.mdx#copy-options). |
#### TPdfOutlineItem
| [Class] `TPdfOutlineItem` → `TPtxPdfNav_OutlineItem` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New related function `TPtxPdfNav_OutlineItem* PtxPdfNav_OutlineItem_Create(` `TPtxPdf_Document* pTargetDocument,``const char* szTitle,` `TPtxPdfNav_Destination* pDestination)` See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). New related function`TPtxPdfNav_OutlineItem* PtxPdfNav_OutlineItem_Copy(``TPtxPdf_Document* pTargetDocument,``TPtxPdfNav_OutlineItem* pOutlineItem,``TPtxPdfNav_OutlineCopyOptions* pOptions)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). See [Copy options](C-interface.mdx#copy-options). |
#### TPdfOutlineItemList
| [Class] `TPdfOutlineItemList` → `TPtxPdfNav_OutlineItemList` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related function `PdfOutlineItemListAppend` → `PtxPdfNav_OutlineItemList_Add`.Renamed remaining related functions `PdfOutlineItemList...` → `PtxPdfNav_OutlineItemList_...` |
#### TPdfPageDisplay
| [Struct] `TPdfPageDisplay` → `TPtxPdfNav_PageDisplay` |
| --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed default value of field `bContinuous` from `TRUE` to `FALSE`.Removed related function `PdfPageDisplayInitialize`. |
#### TPdfPageLayout
| [Enum.] `TPdfPageLayout` → `TPtxPdfNav_PageLayout` |
| --------------------------------------------------------------------- |
| Renamed enum values `ePdfPageLayout...` → `ePtxPdfNav_PageLayout_...` |
#### TPdfViewerNavigationPane
| [Enum.] `TPdfViewerNavigationPane` → `TPtxPdfNav_ViewerNavigationPane` |
| ----------------------------------------------------------------------------------------- |
| Renamed enum values `ePdfViewerNavigationPane...` → `ePtxPdfNav_ViewerNavigationPane_...` |
#### TPdfViewerSettings
| [Class] `TPdfViewerSettings` → `TPtxPdfNav_ViewerSettings` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Renamed related functions `PdfViewerSettings...` → `PtxPdfNav_ViewerSettings_...` New related function `TPtxPdfNav_ViewerSettings* PtxPdfNav_ViewerSettings_Copy(``TPtxPdf_Document* pTargetDocument,``TPtxPdfNav_ViewerSettings* pViewerSettings)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). |
#### TPdfWebLink
| [Class] `TPdfWebLink[` → `TPtxPdfNav_WebLink` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed related function `PdfNewWebLink`. See [Constructors](C-interface.mdx#constructors).Renamed remaining related functions `PdfWebLink...` → `PtxPdfNav_WebLink_...`New related function `TPtxPdfNav_WebLink* PtxPdfNav_WebLink_Create(``TPtxPdf_Document* pTargetDocument,``TPtxGeomReal_Rectangle* pBoundingBox,``const char* szUri)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). See [TPdfLink](#tpdflink) for inherited changes. |
## Prefix PtxSys
| [Struct] `TPdfDate` → `TPtxSys_Date` |
| -------------------------------------------- |
| Removed offset of `1900` from field `iYear`. |
#### TPdfStreamDescriptor
| [Struct] `TPdfStreamDescriptor` → `TPtxSys_StreamDescriptor` |
| --------------------------------------------------------------------------------------------- |
| Renamed related function `PdfCreateFILEStreamDescriptor` → `PtxSysCreateFILEStreamDescriptor` |
---
## .NET interface changes for PDF Toolbox SDK
There are several changes in naming and behavior in the .NET interface to bear in mind when migrating from the 3-Heights® PDF Toolbox API to the PDF Toolbox SDK.
:::note
This page provides the changes between the two products only. For full reference information on the PDF Toolbox SDK, see [.NET API reference](https://api-reference.pdf-tools.com/toolsdk/4.3/dotnet/html/R_Project_API_Reference.htm).
:::
## Namespaces
The company namespace of PDF Tools AG is `PdfTools`, both in 3-Heights® PDF Toolbox API and in PDF Toolbox SDK. In 3-Heights®, most interface elements reside in the namespace `PdfTools.Pdf`, except for the following type,which reside directly in `PdfTools`:
- Point
- Rectangle
- Size
- ErrorCode
- ErrorCodeException
PDF Toolbox SDK introduces the following new namespaces:
| Namespace | Area of usage |
| -------------------------------------------------- | --------------------------- |
| `PdfTools.FourHeights.PdfToolbox` | Base namespace |
| `PdfTools.FourHeights.PdfToolbox.Geometry` | Geometric related |
| `PdfTools.FourHeights.PdfToolbox.Geometry.Real` | For floating point numbers |
| `PdfTools.FourHeights.PdfToolbox.Geometry.Integer` | For integer numbers |
| `PdfTools.FourHeights.PdfToolbox.Pdf` | General PDF related |
| `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations` | Annotation related |
| `PdfTools.FourHeights.PdfToolbox.Pdf.Content` | Page content related |
| `PdfTools.FourHeights.PdfToolbox.Pdf.Forms` | Form field related |
| `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation` | Document navigation related |
## The Sdk class
#### License keys and product version
In 3-Heights®, the public properties `LicenseKey` and `ProductVersion` of the common base class `Internal.NativeObject` allows setting a license key and querying the version of the API.
In PDF Toolbox SDK, this functionality has been moved to the class `Sdk`. Specifically:
- `Sdk.Initialize` must be called to set a license key. See also [License keys](./README.mdx#license-keys).
- `Sdk.Version` gets the API’s version number as a string.
#### The PDF Producer entry
In 3-Heights® PDF Toolbox API, when creating a PDF, the `Metadata` object sets the PDF’s Producer entry via the property `Metadata.Producer`.
In PDF Toolbox SDK, the class `Pdf.Metadata` has no setter for the `Producer` property. Instead, the `Producer` entry for all output PDFs is preconfigured as a string consisting of two parts:
1. The first part (the “base” part) is encodesd in the license key. Hence, this part is determined when buying a licensefrom Pdftools.
2. The second part (the “suffix” part) is configured when calling `Sdk.Initialize` as an argument. It is recommended to use the suffix solely for version information. The assembled “Producer” entry can be obtained after calling `Sdk.Initialize` using the property `Sdk.ProducerFullName`.
## Removal of IDisposable implementation
In PDF Toolbox SDK, the implementation of the [IDisposable interface](../sdk-dotnet.mdx#idisposable-objects) has been removed from all but the following classes:
- `Document`
- `ContentGenerator`
- `TextGenerator`
Native resources are now released automatically when getting or appending a page.
## Value types
In 3-Heights® PDF Toolbox API, interface elements documented as “struct” are actually classes (class), i.e. reference types.
In PDF Toolbox SDK, interface elements documented as “struct” are value types (struct). This affects the following existing interface elements:
- `Point`
- `Size`
- `Rectangle`
- `Transformation`
- `PageDisplay`
and following new interface element:
`Geometry.Integer.Size`
As a consequence, the above types don’t have a constructor and all fields are default constructed. See also [Affine transform objects should be initialized](#affine-transform-objects-should-be-initialized).
## Exceptions
In PDF Toolbox SDK, the `ErrorCodeException` has been renamed to `PdfToolboxException`. The property `ErrorCodeException.Code` has been removed and substituted by the following new classes, each extending `PdfToolboxException`:
- `ConformanceException`
- `CorruptException`
- `LicenseException`
- `PasswordException`
- `UnknownFormatException`
- `UnsupportedFeatureException`
Instead of an `ErrorCodeException` with property `ErrorCodeException.ErrorCodeErrorCode.IO`, a `System.IO.IOException` is generated.
## Renaming
Some interface elements have been renamed. The following principles apply:
- Interface elements that include abbreviations are now written consistently in Pascal case. For example `RGB` → is now `Rgb`, except for two-letter abbreviations, which are written as two capital letters, such as`IO`.
- Some abbreviations have been changed to full words, for example `Char` → `Character`.
- Some words that are repeated in the introduced namespace have been dropped. For example, `AnnotationPopup` → is now `Pdf.Annotations.Popup`.
- Improved clarity, brevity, jargon, and technical correctness.
## Affine transform objects should be initialized
In 3-Heights® PDF Toolbox API, `Transformation` is a class.
In PDF Toolbox SDK, this element has been renamed to `Geometry.Real.AffineTransformation`, and its type has changed to struct (See [Value types](#value-types)).
Specifically, default constructed `Geometry.Real.AffineTransform` objects are not valid. (A matrix with all values 0 is singular.) Default constructed `Geometry.Real.AffineTransform` objects should always be initialized with `Geometry.Real.AffineTransform.Identity`. For example:
```
AffineTransform transform = AffineTransform.Identity;
```
## Creation and copying methods
In 3-Heights® PDF Toolbox API, most document-associated objects are created in an output document by static methods `Document.Create...` and copied from an input document to an output document by static methods `Document.Copy...`, e.g. `Document.CreatePage`, `Document.CopyPage`.
In PDF Toolbox SDK, all these methods have been moved from the `Document` class to the class that is created or copied. For example, method `Document.CreatePage` → `Pdf.Page.Create`.
This affects the following classes:
- `Page`
- `Image`
- `ImageMask`
- `Font`
- `Group`
- `ColorSpace`
- `Paint`
- `Text`
- `Metadata`
- `FileReference`
- `SubForm`
- `GeneralTextField`
- `CombTextField`
- `CheckBoxField`
- `RadioButtonField`
- `ListBoxField`
- `ComboBoxField`
- `NamedDestination`
- `OutlineItem`
- `Annotation`
- `Link`
- `FileAttachmentAnnotation`
- `FreeTextAnnotation`
- `StickyNoteAnnotation`
- `TextStampAnnotation`
- `CustomStampAnnotation`
- `CircleAnnotation`
- `SquareAnnotation`
- `LineAnnotation`
- `PolyLineAnnotation`
- `PolygonAnnotation`
- `FreeDrawingAnnotation`
- `ContentElement`
- `FormFieldNode`
## Constructors
In 3-Heights® PDF Toolbox API, some document-associated objects are created by means of a constructor. E.g. `FitPageDestination.FitPageDestination`.
In PDF Toolbox SDK, most of these document-associated objects are now created and copied with static methods `Create` and `Copy`.
This affects the following classes:
- `EmbeddedPdfLink`
- `FitHeightDestination`
- `FitPageDestination`
- `FitRectangleDestination`
- `FitWidthDestination`
- `LocationZoomDestination`
- `WebLink`
In PDF Toolbox SDK, the following classes (most of them not document-associated) have constructors:
- `Pdf.Encryption`
- `Pdf.Content.ContentExtractor`
- `Pdf.Content.ContentGenerator`
- `Pdf.Content.Fill`
- `Pdf.Content.PageCopyOptions`
- `Pdf.Content.PathGenerator`
- `Pdf.Content.Path`
- `Pdf.Content.Stroke`
- `Pdf.Content.TextGenerator`
- `Pdf.Content.Transparency`
- `Pdf.Navigation.OutlineCopyOptions`
## Unknown PDF conformance
In 3-Heights® PDF Toolbox API, the `Conformance` enumeration has a value `Conformance.Unknown`.
The PDF Toolbox SDK enum `Pdf.Conformance` has no such value. The handling of unknown (i.e. automatically upgrading) PDF conformance is now done as follows:
- In the method `Pdf.Document.Create`, the type of the second argument has changed from `ConformancetoPdf.Conformance?`, where a `null` value has the same meaning as the removed value `Conformance.Unknown`.
- The property `Pdf.Document.Conformance` always returns the current conformance. For input documents, this is the claimed conformance. For output documents, this is either the explicit conformance set when creating or (if created with `null`) the conformance the output PDF would have if closed now.
## Copy options
In 3-Heights® PDF Toolbox API, page copying and outline copying behavior is configurable by means of the `CopyOption` enum.
In PDF Toolbox SDK, this enum has been substituted by new classes:
- `Pdf.PageCopyOptionsUsed` in methods `Pdf.Page.CopyandPdf.Group.CreateFromPage`.
- `Pdf.Navigation.OutlineCopyOptionsUsed` in method `Pdf.Navigation.OutlineItem.Copy`.
Each copying configuration decision is reflected in a class member. Apart from Boolean for on-off decisions, the following enumerations model possible choices:
- `Pdf.CopyStrategy`
- `Pdf.RemovalStrategy`
- `Pdf.NameConflictResolution`
- `Pdf.Forms.FormFieldCopyStrategy`
- `Pdf.Navigation.NamedDestinationCopyStrategy`
This clarifies the copying behavior and allows sensible default values.
## Color space classes
**Class hierarchy**
In 3-Heights® PDF Toolbox API, there is a single class `ColorSpace`, which covers all types of color spaces.
In PDF Toolbox SDK, the `ColorSpaceType` enumeration and the property `ColorSpace.Type` have been removed. Instead, there are the following new classes, all extending `Pdf.Content.ColorSpace`:
- `Pdf.Content.CalibratedGrayColorSpace`
- `Pdf.Content.CalibratedRgbColorSpace`
- `Pdf.Content.DeviceCmykColorSpace`
- `Pdf.Content.DeviceGrayColorSpace`
- `Pdf.Content.DeviceRgbColorSpace`
- `Pdf.Content.IccBasedColorSpace`
- `Pdf.Content.IndexedColorSpace`
- `Pdf.Content.LabColorSpace`
- `Pdf.Content.NChannelColorSpace`
- `Pdf.Content.SeparationColorSpace`
The 3-Heights® PDF Toolbox API color space type `DeviceN` now is subsumed by the more general `Pdf.Content.NChannelColorSpace`.
**Device color spaces versus process color spaces**
In 3-Heights® PDF Toolbox API, the method `Document.CreateDeviceColorSpace` does not necessarily create a device color space, e.g., in case of PDF/A.
In PDF Toolbox SDK, the enumeration `DeviceColorSpaceType` has been renamed to `Pdf.Content.ProcessColorSpaceType`. The class `Pdf.Content.ColorSpace` now has the following static method:
```
Pdf.Content.ColorSpace CreateProcessColorSpace(Pdf.Document targetDocument, Pdf.Content.DeviceColorSpaceType type)
```
This method creates either a device color space, or, in case of PDF/A, a calibrated (grayscale or RGB) or an ICC-based (CMYK) color space.
## Embedded/Associated/Attached files
In 3-Heights® PDF Toolbox API, embedded files, associated files, and files contained in a `FileAttachmentAnnotation` are jointlylisted in the property `Document.EmbeddedFiles`.
In PDF Toolbox SDK, embedded files, associated files, and files contained in file attachment annotations are treated separately. A `Pdf.Document` now has two lists for appending:
- `Pdf.Document.AssociatedFiles`
- `Pdf.Document.PlainEmbeddedFiles`
The former property `Document.EmbeddedFiles` has been renamed to `Pdf.Document.AllEmbeddedFiles`, a read-only list that contains embedded files and files contained in `Pdf.Annotations.FileAttachment` annotations. This list is equivalent to what a viewer normally lists in an embedded files pane,. For example, the “Attachments” pane in the Adobe PDF viewer.
## Annotations
In PDF Toolbox SDK, the following annotation classes have been renamed for technical correctness:
- `FreeDrawingAnnotation` → `Pdf.Annotations.InkAnnotation`
- `CircleAnnotation`→ `Pdf.Annotations.EllipseAnnotation`
- `SquareAnnotation` → `Pdf.Annotations.RectangleAnnotation`
The property `RadioButtenField.CanToggleOff` has been removed. In most PDF viewers, there is no support for this feature.
**Class hierarchy**
In 3-Heights® PDF Toolbox API, `WidgetandLink` extend the base class `Annotation`. In PDF Toolbox SDK, the classes `Pdf.Forms.Widget` and `Pdf.Navigation.Link` have been separated from their former base class. Due to this separation:
A `Pdf.Page` now has the following lists:
- `Pdf.Page.Annotations`
- `Pdf.Page.Links`
- `Pdf.Page.FormFieldWidgets`
The following properties of `Pdf.Annotations.Annotation` have been replicated in `Pdf.Forms.Widget` and `Pdf.Navigation.Link`:
- `BoundingBox`
- `Hidden`
- `NoPrint`
The intermediate base classes `PolyDrawingAnnotation` and `ShapeDrawingAnnotation` have been removed.
All drawing annotations now directly extend the class `Pdf.Annotations.DrawingAnnotation`.Those drawing annotations that have a closed path (`Pdf.Annotations.PolygonAnnotation`, `Pdf.Annotations.EllipseAnnotation`, `Pdf.Annotations.RectangleAnnotation`) have a property `Fill`.
**Class hierarchy comparison**
| 3-Heights® PDF Toolbox (left) | PDF Toolbox SDK (right) |
| ----------------------------- | ----------------------- |
## MaxLength in text fields
In 3-Heights® PDF Toolbox API, the error behavior of the property `TextField.MaxLength` depends on the actual underlying class: `GeneralTextField` allows null values, while `CombTextField` does not.
In PDF Toolbox SDK, the property `TextField.MaxLength` has been removed and replicated in the derived classes `Pdf.Forms.CombTextField` and `Pdf.Forms.GeneralTextField`, in the latter as a nullable `int?`.
## Unified paint creation
In 3-Heights® PDF Toolbox API, there exist three methods for creating a `Paint` object:
- `Document.CreateSolidPaint`
- `Document.CreateAlphaPaint`
- `Document.CreateBlendingPaint`
In PDF Toolbox SDK, these methods have been replaced by a single static method` Pdf.Content.Paint.Create`. See also [Creation and copying methods](#creation-and-copying-methods).
## Separate inside rule from path
In 3-Heights® PDF Toolbox API, the constructor `Path.Path` has an argument `InsideRule rule`.
In PDF Toolbox SDK, this argument is dropped. Instead, the `InsideRule` now is specified in a new member of `Pdf.Content.Fill` when painting the path with `Pdf.Content.ContentGenerator.PaintPath`, or it is specified ina method argument when clipping with `Pdf.Content.ContentGenerator.ClipWithPath`. This removes ambiguity and allows a separated treatment of the inside rule for path filling and path clipping.
## Path and text clipping operations
In 3-Heights® PDF Toolbox API, the `ContentGenerator` supports simultaneous clipping and painting operations.
In PDF Toolbox SDK, path and text clipping operations have been separated from path and text painting operations as follows:
The argument `bool intersectClipPath` has been removed from the method `ContentGenerator.PaintPath`.
The method `TextGenerator.SetRendering` has been removed (see also [Text generator](#text-generator)), and its argument `bool intersectClipping` has been dropped without a replacement.
The new class `Pdf.Content.ContentGenerator` has two new methods for path and text clipping operations:
- `Pdf.Content.ContentGenerator.ClipWithPath`
- `Pdf.Content.ContentGenerator.ClipWithText`
To achieve the same effect of simultaneous clipping and painting, the painting operation has to precede the clipping operation.
## Text generator
In PDF Toolbox SDK, the method `TextGenerator.SetRendering` has been substituted by two separate properties:
- `Pdf.Content.TextGenerator.Fill`
- `Pdf.Content.TextGenerator.Stroke`
## Image size and image mask size
In 3-Heights® PDF Toolbox API, `Image`and `ImageMask` have properties `Width` and `Height`.
In PDF Toolbox SDK, these are substituted by properties `Pdf.Content.Image.Size` and `Pdf.Content.ImageMask.Size`, both of which have the new type `Geometry.Integer.Size`.
---
## Reference
For all changes in the .NET interface between 3-Heights® PDF Toolbox API and the PDF Toolbox SDK, see **[.NET Reference](dotnet-reference.mdx)**.
---
## Reference for changes in .NET interface
This section lists all changes in the .NET interface between 3-Heights® PDF Toolbox API and the PDF Toolbox SDK. Interface elements are ordered alphabetically by PDF Toolbox SDK namespace.
:::note
This page provides the changes between the two products only. For full reference information on the PDF Toolbox SDK, see [.NET API reference](https://api-reference.pdf-tools.com/toolsdk/4.4/dotnet/html/R_Project_API_Reference.htm).
:::
| [Class]`PdfTools.internal.NativeObject` → `PdfTools.FourHeights.PdfToolbox.Internal.NativeObject` |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed members:Removed static property `LicenseKey`.Removed static method `CheckLicense`. Removed static property `ProductVersion`.The above have been substituted by new static members in `Sdk` |
## Base namespace
#### PdfTools.FourHeights.PdfToolbox.ConformanceException
| [Class] `PdfTools.FourHeights.PdfToolbox.ConformanceException` |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`PdfToolboxException`](#pdftoolserrorcodeexception).Substitutes the removed property `ErrorCodeException.Code` with value `ErrorCode.Conformance`. See [Exceptions](./dotnet-interface.mdx#exceptions). |
#### PdfTools.FourHeights.PdfToolbox.CorruptException
| [Class] `PdfTools.FourHeights.PdfToolbox.CorruptException` |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`PdfToolboxException`](#pdftoolserrorcodeexception).Substitutes the removed property `ErrorCodeException.Code` with value `ErrorCode.Corrupt`. See [Exceptions](./dotnet-interface.mdx#exceptions). |
#### PdfTools.ErrorCode
| [Enum.] `PdfTools.ErrorCode` → `PdfTools.FourHeights.PdfToolbox.ErrorCode` |
| -------------------------------------------------------------------------- |
| Removed. See [Exceptions](./dotnet-interface.mdx#exceptions). |
#### PdfTools.ErrorCodeException
| [Class] `PdfTools.ErrorCodeException` → `PdfTools.FourHeights.PdfToolbox.PdfToolboxException` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed property `Code`.In all affected methods and properties, the `ErrorCodeExceptionwithErrorCode.IO` has been substituted by a `System.IO.IOException`. See [Exceptions](./dotnet-interface.mdx#exceptions). |
#### PdfTools.FourHeights.PdfToolbox.LicenseException
| [Class] `PdfTools.FourHeights.PdfToolbox.LicenseException` |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`PdfToolboxException`](#pdftoolserrorcodeexception).Substitutes the removed property `ErrorCodeException.Code` with value `ErrorCode.License`. See [Exceptions](./dotnet-interface.mdx#exceptions). |
#### PdfTools.FourHeights.PdfToolbox.PasswordException
| [Class] `PdfTools.FourHeights.PdfToolbox.PasswordException` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`PdfToolboxException`](#pdftoolserrorcodeexception).Substitutes the removed property `ErrorCodeException.Code` with value `ErrorCode.Password`. See [Exceptions](./dotnet-interface.mdx#exceptions). |
#### PdfTools.FourHeights.PdfToolbox.Sdk
| [Class] `PdfTools.FourHeights.PdfToolbox.Sdk` |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Method `static bool Initialize(string license, string producerSuffix)`Property `static string Version { get ...}``static string ProducerFullName { get...}`.See [The Sdk class](./dotnet-interface.mdx#the-sdk-class). |
#### PdfTools.Pdf.StringMap
| [Class] `PdfTools.Pdf.StringMap` → `PdfTools.FourHeights.PdfToolbox.Pdf.StringMap` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Removed implementation of the `IDisposable` interface. See [Removal of iDisposable implementation](./dotnet-interface.mdx#removal-of-idisposable-implementation). |
#### PdfTools.FourHeights.PdfToolbox.UnknownFormatException
| [Class] `PdfTools.FourHeights.PdfToolbox.UnknownFormatException` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`PdfToolboxException`](#pdftoolserrorcodeexception). Substitutes the removed property `ErrorCodeException.Code` with value `ErrorCode.UnknownFormat`. See [Exceptions](./dotnet-interface.mdx#exceptions). |
#### PdfTools.FourHeights.PdfToolbox.UnsupportedFeatureException
| [Class] `PdfTools.FourHeights.PdfToolbox.UnsupportedFeatureException` |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`PdfToolboxException`](#pdftoolserrorcodeexception). Substitutes the removed property `ErrorCodeException.Code` with value `ErrorCode.UnsupportedFeature`. See [Exceptions](./dotnet-interface.mdx#exceptions). |
## Geometry namespace
#### PdfTools.Pdf.Rotation
| [Enum.] `PdfTools.Pdf.Rotation` → `PdfTools.FourHeights.PdfToolbox.Geometry.Rotation` |
| ------------------------------------------------------------------------------------- |
| Renamed enum value `NoRotation`→ `None`. |
#### PdfTools.Pdf.TextAlignment
| [Enum.] `PdfTools.Pdf.TextAlignment`→ `PdfTools.FourHeights.PdfToolbox.Geometry.HorizontalAlignment` |
| ---------------------------------------------------------------------------------------------------- |
| |
### Pdf.Geometry.Integer namespace
| [Struct] `PdfTools.FourHeights.PdfToolbox.Geometry.Integer.Size` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Fields: `int Width``int Height`Used in [`Image`](#pdftoolspdfimage) and [`ImageMask`](#pdftoolspdfimagemask) to substitute the removed properties `Image.Width`, `Image.Height`, `ImageMask.Width`, and `ImageMask.Height`. See [Image size and image mask size](./dotnet-interface.mdx#image-size-and-image-mask-size). |
### Geometry.Real namespace
#### PdfTools.Point
| [Struct] `PdfTools.Point` → `PdfTools.FourHeights.PdfToolbox.Geometry.Real.Point` |
| --------------------------------------------------------------------------------------------------------------------- |
| Changed type from reference type (class) to value type (struct). See [Value types](./dotnet-interface.mdx#value-types). |
#### PdfTools.Rectangle
| [Struct] `PdfTools.Rectangle`→ `PdfTools.FourHeights.PdfToolbox.Geometry.Real.Rectangle` |
| --------------------------------------------------------------------------------------------------------------------- |
| Changed type from reference type (class) to value type (struct). See [Value types](./dotnet-interface.mdx#value-types). |
#### PdfTools.Size
| [Struct] `PdfTools.Size`→ `PdfTools.FourHeights.PdfToolbox.Geometry.Real.Size` |
| --------------------------------------------------------------------------------------------------------------------- |
| Changed type from reference type (class) to value type (struct). See [Value types](./dotnet-interface.mdx#value-types). |
#### PdfTools.Pdf.Transformation
| [Class → Struct] `PdfTools.Pdf.Transformation`→ `PdfTools.FourHeights.PdfToolbox.Geometry.Real.AffineTransform` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](./dotnet-interface.mdx#removal-of-idisposable-implementation).Changed type from reference type (class) to value type (struct). See [Value types](./dotnet-interface.mdx#value-types).Removed copy constructor.Changed behavior of default constructor. Now returns an invalid `AffineTransform` object with all fields default initialized to `0`. Use property `Identity` to obtain a valid object.See [Affine transform objects should be initialized](./dotnet-interface.mdx#affine-transform-objects-should-be-initialized).Removed method `Rotate`.Renamed method `RotateAround` → `Rotate`.Changed method `Point TransformPoint(Point)`: Changed both the return type `Point` and the argument `typePoint` from reference type (class) to value type (struct). See [Value types](./dotnet-interface.mdx#value-types).New properties:`double A``double B``double C``double D``double E``double F`New property `static AffineTransform Identity { get... }`. See [Affine transform objects should be initialized](./dotnet-interface.mdx#affine-transform-objects-should-be-initialized). |
## Pdf namespace
#### PdfTools.Pdf.Conformance
| [Enum.] `PdfTools.Pdf.Conformance` → `PdfTools.FourHeights.PdfToolbox.Pdf.Conformance` |
| ---------------------------------------------------------------------------------------------------------- |
| Removed enum value `Unknown`. See [Unknown PDF conformance](./dotnet-interface.mdx#unknown-pdf-conformance). |
#### PdfTools.Pdf.CopyOption
| [Enum.] `PdfTools.Pdf.CopyOption` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed. Substituted by [`Pdf.PageCopyOptions`](#pdftoolsfourheightspdftoolboxpdfpagecopyoptions) and [`Pdf.Navigation.OutlineCopyOptions`](#pdftoolsfourheightspdftoolboxpdfnavigationoutlinecopyoptions). See [Copy options](./dotnet-interface.mdx#copy-options). |
#### PdfTools.FourHeights.PdfToolbox.Pdf.CopyStrategy
| [Enum.] `PdfTools.FourHeights.PdfToolbox.Pdf.CopyStrategy` |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Values:`Copy`FlattenRemoveSubstitutes the removed `CopyOption`. See [Copy options](./dotnet-interface.mdx#copy-options). |
#### PdfTools.Pdf.Document
| [Class] `PdfTools.Pdf.Document` → `PdfTools.FourHeights.PdfToolbox.Pdf.Document` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed property `OutlineItems` → `Outline`.Changed type of property `OutputIntent` from [`ColorSpace`](#pdftoolspdfcolorspace) to [`Pdf.Content.IccBasedColorSpace`](#pdftoolsfourheightspdftoolboxpdfcontenticcbasedcolorspace). See [Color space classes](./dotnet-interface.mdx#color-space-classes).Renamed property `EmbeddedFiles` → `AllEmbeddedFiles`. Changed behavior: Appending is not supported anymore. This is a read-only list of all embedded files and all files in [`FileAttachmentAnnotation`](#pdftoolspdffileattachmentannotation). See [Embedded/Associated/Attached files](./dotnet-interface.mdx#embeddedassociatedattached-files).Changed behavior of property `Conformance` for output documents: Always returns the current conformance instead of `removedConformance.Unknown`.Changed signature of method `Document Create(stream streamDesc, Conformance conformance, EncryptionParams encryption)` → `static Pdf.Document Create(Stream streamDesc, Pdf.Conformance? Conformance, Pdf.Encryption Encryption)` Specifically, a `null` value for the second argument is now legal. See [Unknown PDF conformance](./dotnet-interface.mdx#unknown-pdf-conformance).Removed and substituted the following methods:`CreateFileReference` → `Pdf.FileReference.Create``CreateMetadata` → `Pdf.Metadata.Create``CreatePage` → `Pdf.Page.Create``CreateCircleAnnotation` → `Pdf.Annotations.EllipseAnnotation.Create``CreateCustomStampAnnotation` → `Pdf.Annotations.CustomStamp.Create``CreateFileAttachmentAnnotation` → `Pdf.Annotations.FileAttachment.Create``CreateFreeDrawingAnnotation` → `Pdf.Annotations.InkAnnotation.Create``CreateFreeTextAnnotation` → `Pdf.Annotations.FreeText.Create``CreateLineAnnotation` → `Pdf.Annotations.LineAnnotation.Create``CreatePolyLineAnnotation` → `Pdf.Annotations.PolyLineAnnotation.Create``CreatePolygonAnnotation` → `Pdf.Annotations.PolygonAnnotation.Create``CreateSquareAnnotation` → `Pdf.Annotations.RectangleAnnotation.Create``CreateStickyNoteAnnotation` → `Pdf.Annotations.StickyNote.Create``CreateTextStampAnnotationRaw` → `Pdf.Annotations.TextStamp.CreateRaw``CreateAlphaPaint,CreateBlendingPaint,CreateSolidPaint` → `Pdf.Content.Paint.Create`. See [Unified paint creation](./dotnet-interface.mdx#unified-paint-creation).`CreateDeviceColorSpace` → `Pdf.Content.ColorSpace.CreateProcessColorSpace``CreateFont` → `Pdf.Content.Font.Create``CreateGroup` → `Pdf.Content.Group.Create``CreateICCColorSpace` → `Pdf.Content.IccBasedColorSpace.Create``CreateImageMask` → `Pdf.Content.ImageMask.Create``CreateImage` → `Pdf.Content.Image.Create``CreateSystemFont` → `Pdf.Content.Font.CreateFromSystem``CreateText` → `Pdf.Content.Text.Create``CreateCheckBoxField` → `Pdf.Forms.CheckBoxField.Create``CreateCombTextField` → `Pdf.Forms.CombTextField.Create``CreateComboBoxField` → `Pdf.Forms.ComboBoxField.Create``CreateGeneralTextField` → `Pdf.Forms.GeneralTextField.Create``CreateListBoxField` → `Pdf.Forms.ListBoxField.Create``CreateRadioButtonField` → `Pdf.Forms.RadioButtonField.Create``CreateSubForm` → `Pdf.Forms.SubForm.Create``CreateNamedDestination` → `Pdf.Navigation.NamedDestination.Create``CreateOutlineItem` → `Pdf.Navigation.OutlineItem.Create``CopyFileReference` → `Pdf.FileReference.Copy``CopyMetadata` → `Pdf.Metadata.Copy``CopyPage` → `Pdf.Page.Copy``CopyAnnotation` → `Pdf.Annotations.Annotation.Copy``CopyColorSpace` → `Pdf.Content.ColorSpace.Copy``CopyContentElement` → `Pdf.Content.ContentElement.Copy``CopyGroupElementWithoutContent` → `Pdf.Content.GroupElement.CopyWithoutContent``CopyPageAsGroup` → `Pdf.Content.Group.CopyFromPage``CopyFormFieldNode` → `Pdf.Forms.FormFieldNode.Copy``CopyViewerSettings` → `Pdf.Navigation.ViewerSettings.Copy``CopyOutlineItem` → `Pdf.Navigation.OutlineItem.Copy`. See [Creation and copying methods](./dotnet-interface.mdx#creation-and-copying-methods).New property `Pdf.FileReferenceList PlainEmbeddedFiles {get...}`. This is a list of all embedded files that are neither associated nor contained in a [`FileAttachmentAnnotation`](#pdftoolspdffileattachmentannotation). See [Embedded/Associated/Attached files](./dotnet-interface.mdx#embeddedassociatedattached-files). |
#### PdfTools.Pdf.EncryptionParams
| [Struct → Class] `PdfTools.Pdf.EncryptionParams` → `PdfTools.FourHeights.PdfToolbox.Pdf.Encryption` |
| --------------------------------------------------------------------------------------------------- |
| New constructor `Encryption(string userPassword, string ownerPassword, Permission permissions)`. |
#### PdfTools.Pdf.FileReference
| [Class] `PdfTools.Pdf.FileReference` → `PdfTools.FourHeights.PdfToolbox.Pdf.FileReference` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](./dotnet-interface.mdx#removal-of-idisposable-implementation). New method `static FileReference Create(Document targetDocument, Stream data, string name, string mediaType, string description, System.DateTimeOffset modificationDate)`. See [Creation and copying methods](./dotnet-interface.mdx#creation-and-copying-methods).New method `static FileReference Copy(Document targetDocument, FileReference fileReference)`. See [Creation and copying methods](./dotnet-interface.mdx#creation-and-copying-methods). |
#### PdfTools.Pdf.FileReferenceList
| [Class] `PdfTools.Pdf.FileReferenceList` → `PdfTools.FourHeights.PdfToolbox.Pdf.FileReferenceList` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](./dotnet-interface.mdx#removal-of-idisposable-implementation). |
#### PdfTools.Pdf.Metadata
| [Class] `PdfTools.Pdf.Metadata` → `PdfTools.FourHeights.PdfToolbox.Pdf.Metadata` |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](./dotnet-interface.mdx#removal-of-idisposable-implementation).Removed property `Producer`. See [The PDF Producer entry](./dotnet-interface.mdx#the-pdf-producer-entry).Removed property `CreationDate2`.Removed property `ModificationDate2`.Changed type of property `CreationDate` from `System.DateTime?` to `System.DateTimeOffset?`.Changed type of property `ModificationDate` from `System.DateTime?` to `System.DateTimeOffset?`.New method `static Metadata Create(Document targetDocument, Stream xmp)`. See [Creation and copying methods](./dotnet-interface.mdx#creation-and-copying-methods).New method `static Metadata Copy(Document targetDocument, Metadata metadata)`. See [Creation and copying methods](./dotnet-interface.mdx#creation-and-copying-methods). |
#### PdfTools.FourHeights.PdfToolbox.Pdf.NameConflictResolution
| [Enum.] `PdfTools.FourHeights.PdfToolbox.Pdf.NameConflictResolution` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Values:`Merge``Rename`Substitutes the removed [`CopyOption`](#pdftoolspdfcopyoption). See [Copy options](./dotnet-interface.mdx#copy-options). |
#### PdfTools.Pdf.Page
| [Class] `PdfTools.Pdf.Page`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Page` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](./dotnet-interface.mdx#removal-of-idisposable-implementation).Changed the type of properties `BleedBox`, `ArtBox`, and `TrimBox` from reference type `Rectangle` to nullable value type `Rectangle?`. See [Value types](./dotnet-interface.mdx#value-types).Changed the type of property `MediaBox` from reference type `Rectangle` to value type `Rectangle`. See [Value types](./dotnet-interface.mdx#value-types).Renamed method `Crop` → `UpdateSize`. Changed argument type `Rectangle` from reference type to value type.New property `Pdf.Forms.WidgetList FormFieldWidgets { get...}`. See [Annotations](./dotnet-interface.mdx#annotations).New property `Pdf.Navigation.LinkList Links { get...}`. See [Annotations](./dotnet-interface.mdx#annotations).New method `static Page Create(Document targetDocument, Geometry.Real.Size size)`. See [Creation and copying methods](./dotnet-interface.mdx#creation-and-copying-methods).New method `static Page Copy(Document targetDocument, Page page, PageCopyOptions options)`. See [Creation and copying methods](./dotnet-interface.mdx#creation-and-copying-methods). |
#### PdfTools.FourHeights.PdfToolbox.Pdf.PageCopyOptions
| [Class] `PdfTools.FourHeights.PdfToolbox.Pdf.PageCopyOptions` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Members: Constructor `PageCopyOptions()`Property `Pdf.CopyStrategy Links { get... set... }` Default: `CopyStrategy.Copy`Property `Pdf.Forms.FormFieldCopyStrategy FormFields { get... set... }` Default: `FormFieldCopyStrategy.Copy`Property `Pdf.CopyStrategy SignedSignatures { get... set... }` Default: `CopyStrategy.Copy`Property `Pdf.CopyStrategy Annotations { get... set... }` Default: `CopyStrategy.Copy`Property `bool CopyOutlineItems { get... set... }` Default: `true`Property `bool CopyAssociatedFiles { get... set... }` Default: `true`Property `bool CopyLogicalStructure { get... set... }` Default: `true`Property `Pdf.NameConflictResolution FormFieldConflictResolution { get... set... }` Default: `NameConflictResolution.Merge`Property `Pdf.Navigation.NamedDestinationCopyStrategy NamedDestinations { get... set... }` Default: `NamedDestinationCopyStrategy.Copy`Property `bool OptimizeResources { get... set... }` Default: `true` Substitutes the removed [`CopyOption`](#pdftoolspdfcopyoption). See [Copy options](./dotnet-interface.mdx#copy-options). |
#### PdfTools.Pdf.PageList
| [Class] `PdfTools.Pdf.PageList` → `PdfTools.FourHeights.PdfToolbox.Pdf.PageList` |
| ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](./dotnet-interface.mdx#removal-of-idisposable-implementation). |
#### PdfTools.Pdf.Permission
| [Enum.] `PdfTools.Pdf.Permission` → `PdfTools.FourHeights.PdfToolbox.Pdf.Permission` |
| ------------------------------------------------------------------------------------ |
| |
| [Enum.] `PdfTools.FourHeights.PdfToolbox.Pdf.RemovalStrategy` |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Values: `Flatten``Remove`Substitutes the removed [`CopyOption`](#pdftoolspdfcopyoption). See [Copy options](./dotnet-interface.mdx#copy-options). |
### Pdf.Annotations namespace
#### PdfTools.Pdf.Annotation
| [Class] `PdfTools.Pdf.Annotation` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.Annotation` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](./dotnet-interface.mdx).Renamed property `Rectangle` → `BoundingBox`. Changed type `Rectangle` from reference type to value type. See [Value types](./dotnet-interface.mdx#value-types).Removed property `DoPrint`.New property `NoPrint` with reversed meaning of the removed property `DoPrint`.New method `static Annotation Copy(Pdf.Document targetDocument, Annotation annotation)`. See [Creation and copying methods](./dotnet-interface.mdx#creation-and-copying-methods). See [Annotations](./dotnet-interface.mdx#annotations). |
#### PdfTools.Pdf.AnnotationLineEnding
| [Enum.] `PdfTools.Pdf.AnnotationLineEnding` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.LineEnding` |
| ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed enum value `ReversedOpenArrow` → `OpenArrowTail`.Renamed enum value `ReversedClosedArrow` → `ClosedArrowTail`. |
#### PdfTools.Pdf.AnnotationList
| [Class] `PdfTools.Pdf.AnnotationList` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.AnnotationList` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](./dotnet-interface.mdx#removal-of-idisposable-implementation). |
#### PdfTools.Pdf.AnnotationPopup
| [Class] `PdfTools.Pdf.AnnotationPopup` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.Popup` |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed property `Rectangle` → `BoundingBox`. Changed type `Rectangle` from reference type to value type. See [Value types](./dotnet-interface.mdx#value-types). |
#### PdfTools.Pdf.CircleAnnotation
| [Class] `PdfTools.Pdf.CircleAnnotation` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.EllipseAnnotation` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed base class to class `DrawingAnnotation`. See [Annotations](./dotnet-interface.mdx#annotations).New method `static EllipseAnnotation Create(Pdf.Document targetDocument, Geometry.Real.Rectangle boundingBox, Pdf.Content.Stroke stroke, Pdf.Content.Paint fill)`. See [Creation and copying methods](./dotnet-interface.mdx#creation-and-copying-methods).New property `Pdf.Content.Paint Fill { get... }`. See [`DrawingAnnotation`](#pdftoolspdfdrawingannotation) for inherited changes. |
#### PdfTools.Pdf.CustomStampAnnotation
| [Class] `PdfTools.Pdf.CustomStampAnnotation`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.CustomStamp` |
| ----------------------------------------------------------------------------------------------------------- |
| New method `static CustomStampAnnotation Create(Pdf.Document targetDocument, Geometry.Real.Rectangle boundingBox)`. See [Creation and copying methods](./dotnet-interface.mdx#creation-and-copying-methods). See [`StampAnnotation`](#pdftoolspdfstampannotation) for inherited changes.
#### PdfTools.Pdf.DrawingAnnotation
| [Class] `PdfTools.Pdf.DrawingAnnotation` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.DrawingAnnotation` |
| -------------------------------------------------------------------------------------------------------------- |
| See [`MarkupAnnotation`](#pdftoolspdfmarkupannotation) for inherited changes. |
#### PdfTools.Pdf.FileAttachmentAnnotation
| [Class] `PdfTools.Pdf.FileAttachmentAnnotation`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.FileAttachment` |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static FileAttachmentAnnotation Create(Pdf.Document targetDocument, Geometry.Real.Point topleft, Pdf.FileReference attachedFile, Pdf.Content.Paint paint)`. See [Creation and copying methods](./dotnet-interface.mdx#creation-and-copying-methods). See [`MarkupAnnotation`](#pdftoolspdfmarkupannotation) for inherited changes. |
#### PdfTools.Pdf.FileAttachmentIcon
| [Enum.] `PdfTools.Pdf.FileAttachmentIcon` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.FileAttachmentIcon` |
| ---------------------------------------------------------------------------------------------------------------- |
| |
#### PdfTools.Pdf.FreeDrawingAnnotation
| [Class] `PdfTools.Pdf.FreeDrawingAnnotation` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.InkAnnotation` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Changed base class to class `DrawingAnnotation`. See [Annotations](./dotnet-interface.mdx#annotations).New method `static InkAnnotation Create(Pdf.Document targetDocument, Pdf.Content.Path path, Pdf.Content.Stroke stroke)`. See [Creation and copying methods](./dotnet-interface.mdx#creation-and-copying-methods).See [`DrawingAnnotation`](#pdftoolspdfdrawingannotation) for inherited changes. |
#### PdfTools.Pdf.FreeTextAnnotation
| [Class] `PdfTools.Pdf.FreeTextAnnotation` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.FreeText` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| New method `static FreeText Create(Pdf.Document targetDocument, Geometry.Real.RectangleboundingBox, stringcontent, Pdf.Content.Paint paint)`. See [Creation and copying methods](./dotnet-interface.mdx#creation-and-copying-methods). See [`MarkupAnnotation`](#pdftoolspdfmarkupannotation) for inherited changes. |
#### PdfTools.Pdf.HighlightAnnotation
| [Class] `PdfTools.Pdf.HighlightAnnotation`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.Highlight` |
| ------------------------------------------------------------------------------------------------------- |
| See [`TextMarkupAnnotation`](#pdftoolspdftextmarkupannotation) for inherited changes. |
#### PdfTools.Pdf.LineAnnotation
| [Class] `PdfTools.Pdf.LineAnnotation` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.LineAnnotation` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed type `Point` of property `Startfrom` reference type to value type. See [Value types](./dotnet-interface.mdx#value-types).Changed type `Point` of property `Endfrom` reference type to value type. See [Value types](./dotnet-interface.mdx#value-types).New method `static LineAnnotation Create(Pdf.Document targetDocument, Geometry.Real.Point start, Geometry.Real.Point end, Pdf.Content.Stroke stroke)`. See [Creation and copying methods](./dotnet-interface.mdx#creation-and-copying-methods). See [`DrawingAnnotation`](#pdftoolspdfdrawingannotation) for inherited changes. |
#### PdfTools.Pdf.MarkupAnnotation
| [Class] `PdfTools.Pdf.MarkupAnnotation` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.MarkupAnnotation` |
| ------------------------------------------------------------------------------------------------------------ |
| See [`Annotation`](#pdftoolspdfannotation) for inherited changes. |
#### PdfTools.Pdf.MarkupInfo
| [Class] `PdfTools.Pdf.MarkupInfo` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.MarkupInfo` |
| ------------------------------------------------------------------------------------------------ |
| |
#### PdfTools.Pdf.MarkupInfoList
| [Class] `PdfTools.Pdf.MarkupInfoList` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.MarkupInfoList` |
| -------------------------------------------------------------------------------------------------------- |
| |
#### PdfTools.Pdf.PolyDrawingAnnotation
| [Class] `PdfTools.Pdf.PolyDrawingAnnotation` |
| ------------------------------------------------------------- |
| Removed. See [Annotations](./dotnet-interface.mdx#annotations). |
#### PdfTools.Pdf.PolyLineAnnotation
| [Class] `PdfTools.Pdf.PolyLineAnnotation` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.PolyLineAnnotation` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Changed base class to class `DrawingAnnotation`. See [Annotations](./dotnet-interface.mdx#annotations).New method `static PolyLineAnnotation Create(Pdf.Document targetDocument, Pdf.Content.Path path, Pdf.Content.Stroke stroke)`. See [Creation and copying methods](./dotnet-interface.mdx#creation-and-copying-methods). See [`DrawingAnnotation`](#pdftoolspdfdrawingannotation) for inherited changes. |
#### PdfTools.Pdf.PolygonAnnotation
| [Class] `PdfTools.Pdf.PolygonAnnotation` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.PolygonAnnotation` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed base class to class `DrawingAnnotation`. See [Annotations](./dotnet-interface.mdx#annotations).New method `static PolygonAnnotation Create(Pdf.Document targetDocument, Pdf.Content.Path path, Pdf.Content.Stroke stroke)`. See [Creation and copying methods](./dotnet-interface.mdx#creation-and-copying-methods). See [`DrawingAnnotation`](#pdftoolspdfdrawingannotation) for inherited changes. |
#### PdfTools.Pdf.ShapeDrawingAnnotation
| [Class] `PdfTools.Pdf.ShapeDrawingAnnotation` |
| ------------------------------------------------------------- |
| Removed. See [Annotations](./dotnet-interface.mdx#annotations). |
#### PdfTools.Pdf.SquareAnnotation
| [Class] `PdfTools.Pdf.SquareAnnotation` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.RectangleAnnotation` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed base class to class [`DrawingAnnotation`](#pdftoolspdfdrawingannotation). See [Annotations](./dotnet-interface.mdx#annotations).New method `static PolylineAnnotation Create(Pdf.Document targetDocument, Geometry.Real.Rectangle boundingBox, Pdf.Content.Stroke stroke, Pdf.Content.Fill fill)`. See [Creation and copying methods](./dotnet-interface.mdx#creation-and-copying-methods).New property `Pdf.Content.Fill Fill { get... }`. See [`DrawingAnnotation`](#pdftoolspdfdrawingannotation) for inherited changes. |
#### PdfTools.Pdf.SquigglyAnnotation
| [Class] `PdfTools.Pdf.SquigglyAnnotation` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.Squiggly` |
| ------------------------------------------------------------------------------------------------------ |
| See [`HighlightAnnotation`](#pdftoolspdfhighlightannotation) for inherited changes. |
#### PdfTools.Pdf.StampAnnotation
| [Class] `PdfTools.Pdf.StampAnnotation` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.Stamp` |
| ------------------------------------------------------------------------------------------------ |
| See [`MarkupAnnotation`](#pdftoolspdfmarkupannotation) for inherited changes. |
#### PdfTools.Pdf.StickyNoteAnnotation
| [Class] `PdfTools.Pdf.StickyNoteAnnotation`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.StickyNote` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| New method `static StickyNote Create(Pdf.Document targetDocument, Geometry.Real.Point topleft, string content, Pdf.Content.Paint paint)`. See [Creation and copying](./dotnet-interface.mdx#creation-and-copying-methods) methods. See [`MarkupAnnotation`](#pdftoolspdfmarkupannotation) for inherited changes. |
#### PdfTools.Pdf.StrikeThroughAnnotation
| [Class] `PdfTools.Pdf.StrikeThroughAnnotation`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.StrikeThrough` |
| --------------------------------------------------------------------------------------------------------------- |
| See [`TextMarkupAnnotation`](#pdftoolspdftextmarkupannotation) for inherited changes. |
#### PdfTools.Pdf.TextInsertAnnotation
| [Class] `PdfTools.Pdf.TextInsertAnnotation` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.TextInsert` |
| ---------------------------------------------------------------------------------------------------------- |
| See [`TextMarkupAnnotation`](#pdftoolspdftextmarkupannotation) for inherited changes. |
#### PdfTools.Pdf.TextMarkupAnnotation
| [Class] `PdfTools.Pdf.TextMarkupAnnotation` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.TextMarkup` |
| ---------------------------------------------------------------------------------------------------------- |
| See [`MarkupAnnotation`](#pdftoolspdfmarkupannotation) for inherited changes. |
#### PdfTools.Pdf.TextStampAnnotation
| [Class] `PdfTools.Pdf.TextStampAnnotation` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.TextStamp` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static TextStamp Create(Pdf.Document targetDocument, Geometry.Real.Point topleft, double?height, TextStampType type, string content)`. See [Creation and copying methods](./dotnet-interface.mdx#creation-and-copying-methods). See [`StampAnnotation`](#pdftoolspdfstampannotation) for inherited changes. |
#### PdfTools.Pdf.TextStampType
| [Enum.] `PdfTools.Pdf.TextStampType` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.TextStampType` |
| ------------------------------------------------------------------------------------------------------ |
| |
#### PdfTools.Pdf.UnderlineAnnotation
| [Class] `PdfTools.Pdf.UnderlineAnnotation` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.Underline` |
| -------------------------------------------------------------------------------------------------------- |
| See [`TextMarkupAnnotation`](#pdftoolspdftextmarkupannotation) for inherited changes. |
### Pdf.Content namespace
#### PdfTools.Pdf.BlendMode
| [Enum.] `PdfTools.Pdf.BlendMode`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Content.BlendMode` |
| ----------------------------------------------------------------------------------------- |
| |
#### PdfTools.FourHeights.PdfToolbox.Pdf.Content.CalibratedGrayColorSpace
| [Class] `PdfTools.FourHeights.PdfToolbox.Pdf.Content.CalibratedGrayColorSpace` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`Pdf.Content.ColorSpace`](#pdftoolspdfcolorspace). Substitutes the removed enum `ColorSpaceType`. See [Color space classes](./dotnet-interface.mdx#color-space-classes). |
#### PdfTools.FourHeights.PdfToolbox.Pdf.Content.CalibratedRgbColorSpace
| [Class] `PdfTools.FourHeights.PdfToolbox.Pdf.Content.CalibratedRgbColorSpace` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`Pdf.Content.ColorSpace`](#pdftoolspdfcolorspace). Substitutes the removed enum `ColorSpaceType`. See [Color space classes](./dotnet-interface.mdx#color-space-classes). |
#### PdfTools.FourHeights.PdfToolbox.Pdf.Content.CalibratedCmykColorSpace
| [Class] `PdfTools.FourHeights.PdfToolbox.Pdf.Content.CalibratedCmykColorSpace` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`Pdf.Content.ColorSpace`](#pdftoolspdfcolorspace). Substitutes the removed enum `ColorSpaceType`. See [Color space classes](./dotnet-interface.mdx#color-space-classes). |
#### PdfTools.Pdf.ColorSpace
| [Class] `PdfTools.Pdf.ColorSpace` → `PdfTools.FourHeights.PdfToolbox.Pdf.Content.ColorSpace` |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](./dotnet-interface.mdx#removal-of-idisposable-implementation).Renamed property `Components` → `ComponentCount`.Removed property `Type`.Removed property `Name`.New method `static ColorSpace CreateProcessColorSpace(Pdf.Document targetDocument, Pdf.Content.ProcessColorSpaceType type)`New method `static ColorSpace Copy(Pdf.Document targetDocument, ColorSpace colorSpace)`. See [Creation and copying methods](./dotnet-interface.mdx#creation-and-copying-methods). See [Color space classes](./dotnet-interface.mdx#color-space-classes). |
#### PdfTools.Pdf.ColorSpaceType
| [Enum.] `PdfTools.Pdf.ColorSpaceType` |
| ----------------------------------------------------------------------------- |
| Removed. See [Color space classes](./dotnet-interface.mdx#color-space-classes). |
#### PdfTools.Pdf.Content
| [Class] `PdfTools.Pdf.Content`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Content.Content` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](./dotnet-interface.mdx#removal-of-idisposable-implementation). |
#### PdfTools.Pdf.ContentElement
| [Class] `PdfTools.Pdf.ContentElement`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Content.ContentElement` |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](./dotnet-interface.mdx#removal-of-idisposable-implementation).Changed type `Rectangle` of property `BoundingBox` from reference type to value type. See [Value types](./dotnet-interface.mdx#value-types).Changed type `Transformation` → `Geometry.Real.AffineTransform` of property `Transform` from reference type to value type. See [Value types](./dotnet-interface.mdx#value-types).New method `static Content elementCopy(Pdf.Document targetDocument, ContentElement contentElement)`. See [Creation and copying methods.](./dotnet-interface.mdx#creation-and-copying-methods) |
#### PdfTools.Pdf.ContentExtractor
| [Class] `PdfTools.Pdf.ContentExtractor`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Content.ContentExtractor` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](./dotnet-interface.mdx#removal-of-idisposable-implementation). |
#### PdfTools.Pdf.ContentGenerator
| [Class] `PdfTools.Pdf.ContentGenerator`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Content.ContentGenerator` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Changed method `void PaintPath(Path path, Paint fill,StrokeParams stroke, bool intersectClipping)`→ `void PaintPath(Path path,Fill fill, Stroke stroke)`. See [Separate inside rule from path](./dotnet-interface.mdx#separate-inside-rule-from-path) and [Path and text clipping operations](./dotnet-interface.mdx#path-and-text-clipping-operations).Changed behavior of methods `PaintImage` and `PaintImageMask`: Value `null` for second argument of type `Rectangle` is not supported anymore.New method `void ClipWithPath(Pdf.Content.Path path, Pdf.Content.InsideRule InsideRule)`. See [Separate inside rule from path](./dotnet-interface.mdx#separate-inside-rule-from-path) and [Path and text clipping operations](./dotnet-interface.mdx#path-and-text-clipping-operations).New method `void ClipWithText(Pdf.Content.Text text)`. See [Path and text clipping operations](./dotnet-interface.mdx#path-and-text-clipping-operations). |
#### PdfTools.Pdf.DeviceColorSpaceType
| [Enum.] `PdfTools.Pdf.DeviceColorSpaceType` → `PdfTools.FourHeights.PdfToolbox.Pdf.Content.ProcessColorSpaceType` |
| ----------------------------------------------------------------------------------------------------------------- |
| Renamed enum value `RGB` → `Rgb`.Renamed enum value `CMYK` → `Cmyk`. |
#### PdfTools.FourHeights.PdfToolbox.Pdf.Content.DeviceGrayColorSpace
| [Class] `PdfTools.FourHeights.PdfToolbox.Pdf.Content.DeviceGrayColorSpace` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`Pdf.Content.ColorSpace`](#pdftoolspdfcolorspace). Substitutes the removed enum `ColorSpaceType`. See [Color space classes](./dotnet-interface.mdx#color-space-classes). |
#### PdfTools.FourHeights.PdfToolbox.Pdf.Content.DeviceCmykColorSpace
| [Class] `PdfTools.FourHeights.PdfToolbox.Pdf.Content.DeviceCmykColorSpace` |
| -------------------------------------------------------------------------- |
| Extends [`Pdf.Content.ColorSpace`](#pdftoolspdfcolorspace). Substitutes the removed enum `ColorSpaceType`. See [Color space classes](./dotnet-interface.mdx#color-space-classes).
#### PdfTools.FourHeights.PdfToolbox.Pdf.Content.DeviceRgbColorSpace
| [Class] `PdfTools.FourHeights.PdfToolbox.Pdf.Content.DeviceRgbColorSpace` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`Pdf.Content.ColorSpace`](#pdftoolspdfcolorspace). Substitutes the removed enum `ColorSpaceType`. See [Color space classes](./dotnet-interface.mdx#color-space-classes). |
#### PdfTools.Pdf.FillParams
| [Struct → class] `PdfTools.Pdf.FillParams[struct → class]` → `PdfTools.FourHeights.PdfToolbox.Pdf.Content.Fill` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Removed constructor `FillParams(Paint paint, InsideRule fillRule)`.Renamed property `FillRule` → `InsideRule`. See [Separate inside rule from path](./dotnet-interface.mdx#separate-inside-rule-from-path).New constructor `Fill(Paint paint)`. See [Creation and copying methods.](./dotnet-interface.mdx#creation-and-copying-methods) |
#### PdfTools.Pdf.Font
| [Class] `PdfTools.Pdf.Font`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Content.Font` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](./dotnet-interface.mdx#removal-of-idisposable-implementation). Renamed method `GetCharWidth→GetCharacterWidth`.New method `static Font Create(Pdf.Document targetDocument, Stream stream, bool embedded)`. See [Creation and copying methods.](./dotnet-interface.mdx#creation-and-copying-methods)New method `static Font CreateFromSystem(Pdf.Document targetDocument, string family,string style, bool embedded)`. See [Creation and copying methods.](./dotnet-interface.mdx#creation-and-copying-methods). See [Creation and copying methods.](./dotnet-interface.mdx#creation-and-copying-methods) |
#### PdfTools.Pdf.Group
| [Class] `PdfTools.Pdf.Group`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Content.Group` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](./dotnet-interface.mdx#removal-of-idisposable-implementation).Changed type `Size` of property `Size` from reference type to value type. See [Value types](./dotnet-interface.mdx#value-types).New method `static Group Create(Pdf.Document targetDocument, Geometry.Real.Size size)`. See [Creation and copying methods.](./dotnet-interface.mdx#creation-and-copying-methods)New method `static Group CreateFromPage(Pdf.Document targetDocument, Pdf.Page page,Pdf.PageCopyOptions copyOptions)`. See [Creation and copying methods.](./dotnet-interface.mdx#creation-and-copying-methods) |
#### PdfTools.Pdf.GroupElement
| [Class] `PdfTools.Pdf.GroupElement`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Content.GroupElement` |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static GroupElement CopyWithoutContent(Pdf.Document targetDocument, Group Element groupElement)` See [Creation and copying methods.](./dotnet-interface.mdx#creation-and-copying-methods). See [ContentElement](#pdftoolspdfcontentelement) for inherited changes. |
#### PdfTools.FourHeights.PdfToolbox.Pdf.Content.IccBasedColorSpace
| [Class] `PdfTools.FourHeights.PdfToolbox.Pdf.Content.IccBasedColorSpace` |
| ------------------------------------------------------------------------ |
| Extends [Pdf.Content.ColorSpace](#pdftoolspdfcolorspace).
Method `static Pdf.Content.IccBasedColorSpace Create(Pdf.Document targetDocument, Stream profile)`. See [Creation and copying methods.](./dotnet-interface.mdx#creation-and-copying-methods) Substitutes the removed enum `ColorSpaceType`. See [Color space classes](./dotnet-interface.mdx#color-space-classes).
#### PdfTools.Pdf.Image
| [Class] `PdfTools.Pdf.Image`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Content.Image` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](./dotnet-interface.mdx#removal-of-idisposable-implementation).Removed property `Width`. Replaced by new property `Size`.Removed property `Height`. Replaced by new property `Size`.New method `static ImageCreate(Pdf.Document targetDocument, Stream stream)`. See [Creation and copying methods.](./dotnet-interface.mdx#creation-and-copying-methods)New property `Geometry.Integer.SizeSize { get... }`. See [Image size and image mask size](./dotnet-interface.mdx#image-size-and-image-mask-size). |
#### PdfTools.Pdf.ImageElement
| [Class] `PdfTools.Pdf.ImageElement` → `PdfTools.FourHeights.PdfToolbox.Pdf.Content.ImageElement` |
| ------------------------------------------------------------------------------------------------ |
| See [ContentElement](#pdftoolspdfcontentelement) for inherited changes. |
#### PdfTools.Pdf.ImageMask
| [Class] `PdfTools.Pdf.ImageMask` → `PdfTools.FourHeights.PdfToolbox.Pdf.Content.ImageMask` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](./dotnet-interface.mdx#removal-of-idisposable-implementation).Removed property `Width`. Replaced by nsew property `Size`.Removed property `Height`. Replaced by new property `Size`.New method `static ImageMask Create(Pdf.Document targetDocument, Stream stream)`. See [Creation and copying methods.](./dotnet-interface.mdx#creation-and-copying-methods)New property `Geometry.Integer.SizeSize { get... }`. See [Image size and image mask size](./dotnet-interface.mdx#image-size-and-image-mask-size). |
#### PdfTools.Pdf.ImageMaskElement
| [Class] `PdfTools.Pdf.ImageMaskElement` → `PdfTools.FourHeights.PdfToolbox.Pdf.Content.ImageMaskElement` |
| -------------------------------------------------------------------------------------------------------- |
| See [ContentElement](#pdftoolspdfcontentelement) for inherited changes. |
#### PdfTools.FourHeights.PdfToolbox.Pdf.Content.IndexedColorSpace
| [Class] `PdfTools.FourHeights.PdfToolbox.Pdf.Content.IndexedColorSpace` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`Pdf.Content.ColorSpace`](#pdftoolspdfcolorspace). Substitutes the removed enum `ColorSpaceType`. See [Color space classes](./dotnet-interface.mdx#color-space-classes). |
#### PdfTools.Pdf.InsideRule
| [Enum.] `PdfTools.Pdf.InsideRule`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Content.InsideRule` |
| ------------------------------------------------------------------------------------------- |
| |
#### PdfTools.FourHeights.PdfToolbox.Pdf.Content.LabColorSpace
| [Class] `PdfTools.FourHeights.PdfToolbox.Pdf.Content.LabColorSpace` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`Pdf.Content.ColorSpace`](#pdftoolspdfcolorspace). Substitutes the removed enum `ColorSpaceType`. See [Color space classes](./dotnet-interface.mdx#color-space-classes). |
#### PdfTools.Pdf.LineCapStyle
| [Enum.] `PdfTools.Pdf.LineCapStyle`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Content.LineCapStyle` |
| ----------------------------------------------------------------------------------------------- |
| |
#### PdfTools.Pdf.LineJoinStyle
| [Enum.] `PdfTools.Pdf.LineJoinStyle`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Content.LineJoinStyle` |
| ------------------------------------------------------------------------------------------------- |
| |
#### PdfTools.FourHeights.PdfToolbox.Pdf.Content.NChannelColorSpace
| [Class] `PdfTools.FourHeights.PdfToolbox.Pdf.Content.NChannelColorSpace` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`Pdf.Content.ColorSpace`](#pdftoolspdfcolorspace). Substitutes the removed enum `ColorSpaceType`. See [Color space classes](./dotnet-interface.mdx#color-space-classes). |
#### PdfTools.Pdf.Paint
| [Class] `PdfTools.Pdf.Paint` → `PdfTools.FourHeights.PdfToolbox.Pdf.Content.Paint` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](./dotnet-interface.mdx#removal-of-idisposable-implementation).New method `static PaintCreate(Pdf.Document targetDocument, Pdf.Content.ColorSpace colorSpace, double[]color, Pdf.Content.Transparency transparency)`. See [Creation and copying methods](./dotnet-interface.mdx#creation-and-copying-methods) and [Unified paint creation](./dotnet-interface.mdx#unified-paint-creation). |
#### PdfTools.Pdf.Path
| [Class] `PdfTools.Pdf.Path` → `PdfTools.FourHeights.PdfToolbox.Pdf.Content.Path` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](./dotnet-interface.mdx#removal-of-idisposable-implementation).Changed constructor `Path(FillRule rule)` → `Path()`. See [Separate inside rule from path](./dotnet-interface.mdx#separate-inside-rule-from-path). |
#### PdfTools.Pdf.PathElement
| [Class] `PdfTools.Pdf.PathElement` → `PdfTools.FourHeights.PdfToolbox.Pdf.Content.PathElement` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed type `Rectangle` of property `AlignmentBox` from reference type to value type. See [Value types](./dotnet-interface.mdx#value-types). See [ContentElement](#pdftoolspdfcontentelement) for inherited changes. |
#### PdfTools.Pdf.PathGenerator
| [Class] `PdfTools.Pdf.PathGenerator` → `PdfTools.FourHeights.PdfToolbox.Pdf.Content.PathGenerator` |
| --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed types `Point` and `Rectangle` (used in all methods) from reference type to value type. See [Value types](./dotnet-interface.mdx#value-types). |
#### PdfTools.FourHeights.PdfToolbox.Pdf.Content.SeparationColorSpace
| [Class] `PdfTools.FourHeights.PdfToolbox.Pdf.Content.SeparationColorSpace` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`Pdf.Content.ColorSpace`](#pdftoolspdfcolorspace). Substitutes the removed enum `ColorSpaceType`. See [Color space classes](./dotnet-interface.mdx#color-space-classes). |
#### PdfTools.Pdf.ShadingElement
| [Class] `PdfTools.Pdf.ShadingElement` → `PdfTools.FourHeights.PdfToolbox.Pdf.Content.ShadingElement` |
| ---------------------------------------------------------------------------------------------------- |
| See [ContentElement](#pdftoolspdfcontentelement) for inherited changes. |
#### PdfTools.Pdf.StrokeParams
| [Struct → class] `PdfTools.Pdf.StrokeParams`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Content.Stroke` |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed constructor `StrokeParams(Paint paint, double lineWidth, LineCapStyle lineCapStyle, LineJoinStyle lineJoinStyle, double[] dashArray, double dashPhase, double miterLimit).` New constructor `Stroke(Paint paint, double lineWidth)`. See [Creation and copying methods.](./dotnet-interface.mdx#creation-and-copying-methods) |
#### PdfTools.Pdf.Text
| [Class] `PdfTools.Pdf.Text` → `PdfTools.FourHeights.PdfToolbox.Pdf.Content.Text` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](./dotnet-interface.mdx#removal-of-idisposable-implementation).New method `static TextCreate(Pdf.Document targetDocument)`. See [Creation and copying methods.](./dotnet-interface.mdx#creation-and-copying-methods) |
#### PdfTools.Pdf.TextElement
| [Class] `PdfTools.Pdf.TextElement` → `PdfTools.FourHeights.PdfToolbox.Pdf.Content.TextElement` |
| ---------------------------------------------------------------------------------------------- |
| See [ContentElement](#pdftoolspdfcontentelement) for inherited changes. |
#### PdfTools.Pdf.TextFragment
| [Class] `PdfTools.Pdf.TextFragment` → `PdfTools.FourHeights.PdfToolbox.Pdf.Content.TextFragment` |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](./dotnet-interface.mdx#removal-of-idisposable-implementation).Renamed property `UnicodeString` → `Text`.Changed type `Rectangle` of property `BoundingBox` from reference type to value type. See [Value types](./dotnet-interface.mdx#value-types). |
#### PdfTools.Pdf.TextGenerator
| [Class] `PdfTools.Pdf.TextGenerator` → `PdfTools.FourHeights.PdfToolbox.Pdf.Content.TextGenerator` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed constructor from `TextGenerator(Text text, Font font, double fontSize, Point location)` → `TextGenerator(Text text, Font font, double fontSize, Geometry.Real.Point?location)` Removed method `SetRendering`. Replaced by properties `Fill` and `Stroke`. See [Text generator](./dotnet-interface.mdx#text-generator).Renamed property `CharSpacing` → `CharacterSpacing`. See [Renaming](./dotnet-interface.mdx#renaming).New property `PaintFill { get... set... }`.New property `Stroke Stroke { get... set... }`. |
| [Struct → class] `PdfTools.Pdf.TransparencyParams`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Content.Transparency` |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed constructor `TransparencyParams(BlendMode blendMode, double constAlpha)`.Renamed property `ConstAlpha` → `Alpha`.New constructor `Transparency(double alpha)`. |
#### PdfTools.Pdf.UngroupingSet
| [Enum.] `PdfTools.Pdf.UngroupingSet` → `PdfTools.FourHeights.PdfToolbox.Pdf.Content.UngroupingSelection` |
| -------------------------------------------------------------------------------------------------------- |
| |
### Pdf.Forms namespaces
#### PdfTools.Pdf.CheckBoxField
| [Class] `PdfTools.Pdf.CheckBoxField` → `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.CheckBox` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static CheckBox Create(Pdf.Document targetDocument)`. See [Creation and copying methods.](./dotnet-interface.mdx#creation-and-copying-methods). See [FormField](#pdftoolspdfformfield) for inherited changes. |
#### PdfTools.Pdf.ChoiceField
| [Class] `PdfTools.Pdf.ChoiceField` → `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.ChoiceField` |
| -------------------------------------------------------------------------------------------- |
| See [FormField](#pdftoolspdfformfield) for inherited changes. |
#### PdfTools.Pdf.ChoiceItem
| [Class] `PdfTools.Pdf.ChoiceItem` → `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.ChoiceItem` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](./dotnet-interface.mdx#removal-of-idisposable-implementation). |
#### PdfTools.Pdf.ChoiceItemList
| [Class] `PdfTools.Pdf.ChoiceItemList` → `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.ChoiceItemList` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](./dotnet-interface.mdx#removal-of-idisposable-implementation). |
#### PdfTools.Pdf.ComboBoxField
| [Class] `PdfTools.Pdf.ComboBoxField` → `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.ComboBox` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static ComboBox Create(Pdf.Document targetDocument)`. See [Creation and copying methods.](./dotnet-interface.mdx#creation-and-copying-methods)See [ChoiceField](#pdftoolspdfchoicefield) for inherited changes. |
#### PdfTools.Pdf.CombTextField
| [Class] `PdfTools.Pdf.CombTextField` → `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.CombTextField` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static CombTextField Create(Pdf.Document targetDocument, int maxLength)`. See [Creation and copying methods.](./dotnet-interface.mdx#creation-and-copying-methods)New property `int MaxLength { get... set... }`. See [MaxLength in text fields](./dotnet-interface.mdx#maxlength-in-text-fields). See [TextField](#pdftoolspdftextfield) for inherited changes. |
#### PdfTools.Pdf.FormField
| [Class] `PdfTools.Pdf.FormField` → `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.Field` |
| ------------------------------------------------------------------------------------ |
| Changed type `Rectangle` of argument in method `AddNewWidget` from reference type to value type. See [Value types](./dotnet-interface.mdx#value-types). See [FormFieldNode](#pdftoolspdfformfieldnode) for inherited changes.
#### PdfTools.FourHeights.PdfToolbox.Pdf.Forms.FormFieldCopyStrategy
| [Enum.] `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.FormFieldCopyStrategy` |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Values: `Copy``Flatten``Remove``CopyAndUpdateWidgets`Substitutes the removed `CopyOption`. See [Copy options](./dotnet-interface.mdx#copy-options). |
#### PdfTools.Pdf.FormFieldNode
| [Class] `PdfTools.Pdf.FormFieldNode` → `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.FieldNode` |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](./dotnet-interface.mdx#removal-of-idisposable-implementation).New method `static FieldNode Copy(Pdf.Document targetDocument, FieldNode fieldNode)`. See [Creation and copying methods.](./dotnet-interface.mdx#creation-and-copying-methods) |
#### PdfTools.Pdf.FormFieldNodeMap
| [Class] `PdfTools.Pdf.FormFieldNodeMap` → `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.FieldNodeMap` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](./dotnet-interface.mdx#removal-of-idisposable-implementation). |
#### PdfTools.Pdf.GeneralTextField
| [Class] `PdfTools.Pdf.GeneralTextField` → `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.GeneralTextField` |
| ------------------------------------------------------------------------------------------------------ |
| New method `static GeneralTextField Create(Pdf.Document targetDocument)`. See [Creation and copying methods.](./dotnet-interface.mdx#creation-and-copying-methods)
New property `int? MaxLength { get... set... }`. See [MaxLength in text fields](./dotnet-interface.mdx#maxlength-in-text-fields). See [TextField](#pdftoolspdftextfield) for inherited changes. |
#### PdfTools.Pdf.ListBoxField
| [Class] `PdfTools.Pdf.ListBoxField` → `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.ListBox` |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static ListBox Create(Pdf.Document targetDocument)`. See [Creation and copying methods.](./dotnet-interface.mdx#creation-and-copying-methods). See [ChoiceField](#pdftoolspdfchoicefield) for inherited changes. |
#### PdfTools.Pdf.PushButtonField
| [Class] `PdfTools.Pdf.PushButtonField` → `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.PushButton` |
| ----------------------------------------------------------------------------------------------- |
| |
#### PdfTools.Pdf.RadioButton
| [Class] `PdfTools.Pdf.RadioButton` → `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.RadioButton` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](./dotnet-interface.mdx#removal-of-idisposable-implementation).Changed type `Rectangle` of argument in method `AddNewWidget` from reference type to value type. See [Value types](./dotnet-interface.mdx#value-types). |
#### PdfTools.Pdf.RadioButtonField
| [Class] `PdfTools.Pdf.RadioButtonField` → `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.RadioButtonGroup` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Removed property `CanToggleOff`.New method `static RadioButtonGroup Create(Pdf.Document targetDocument)`. See [Creation and copying methods.](./dotnet-interface.mdx#creation-and-copying-methods). See [FormField](#pdftoolspdfformfield) for inherited changes. |
#### PdfTools.Pdf.RadioButtonList
| [Class] `PdfTools.Pdf.RadioButtonList` → `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.RadioButtonList` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](./dotnet-interface.mdx#removal-of-idisposable-implementation). |
#### PdfTools.Pdf.SignatureField
| [Class] `PdfTools.Pdf.SignatureField` → `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.SignatureField` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](./dotnet-interface.mdx#removal-of-idisposable-implementation). |
#### PdfTools.Pdf.SignatureFieldList
| [Class] `PdfTools.Pdf.SignatureFieldList` → `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.SignatureFieldList` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](./dotnet-interface.mdx#removal-of-idisposable-implementation). |
#### PdfTools.Pdf.SubForm
| [Class] `PdfTools.Pdf.SubForm` → `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.SubForm` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static SubForm Create(Pdf.DocumenttargetDocument)`. See [Creation and copying methods.](./dotnet-interface.mdx#creation-and-copying-methods). See [FormFieldNode](#pdftoolspdfformfieldnode) for inherited changes. |
#### PdfTools.Pdf.TextField
| [Class] `PdfTools.Pdf.TextField` → `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.TextField` |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed property `MaxLength`. See [MaxLength in text fields](./dotnet-interface.mdx#maxlength-in-text-fields). See [FormFieldNode](#pdftoolspdfformfieldnode) for inherited changes. |
#### PdfTools.Pdf.Widget
| [Class] `PdfTools.Pdf.Widget` → `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.Widget` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed inheritance from classAnnotation.SeeAnnotations.Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](./dotnet-interface.mdx#removal-of-idisposable-implementation).Duplicated property `Geometry.Real.Rectangle BoundingBox { get...}` from former `baseclassAnnotation`.Duplicated property `bool Hidden { get... }` from former base `classAnnotation`.Duplicated property `bool NoPrint { get...}` from former base `classAnnotation`. |
#### PdfTools.Pdf.WidgetList
| [Class] `PdfTools.Pdf.WidgetList` → `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.WidgetList` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](./dotnet-interface.mdx#removal-of-idisposable-implementation). |
### Pdf.Navigation namespace
#### PdfTools.Pdf.Destination
| [Class] `PdfTools.Pdf.Destination` → `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.Destination` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](./dotnet-interface.mdx#removal-of-idisposable-implementation). |
#### PdfTools.Pdf.DirectDestination
| [Class] `PdfTools.Pdf.DirectDestination` → `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.DirectDestination` |
| ------------------------------------------------------------------------------------------------------------- |
| See [Destination](#pdftoolspdfdestination) for inherited changes. |
#### PdfTools.Pdf.EmbeddedPdfLink
| [Class] `PdfTools.Pdf.EmbeddedPdfLink` → `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.EmbeddedPdfLink` |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed constructor. See [Constructors](./dotnet-interface.mdx#constructors).New method `static EmbeddedPdfLink Create(Pdf.Document targetDocument, Geometry.Real.Rectangle boundingBox, Pdf.FileReference fileReference)`. See [Creation and copying methods.](./dotnet-interface.mdx#creation-and-copying-methods)See [Link](#pdftoolspdflink) for inherited changes. |
#### PdfTools.Pdf.FitHeightDestination
| [Class] `PdfTools.Pdf.FitHeightDestination` → `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.FitHeightDestination` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed constructor. See [Constructors](./dotnet-interface.mdx#constructors).New method `static FitHeightDestination Create(Pdf.Document targetDocument,Pdf.Pagepage, bool fitActualContent)`. See [Creation and copying methods.](./dotnet-interface.mdx#creation-and-copying-methods). See [DirectDestination](#pdftoolspdfdirectdestination) for inherited changes. |
#### PdfTools.Pdf.FitPageDestination
| [Class] `PdfTools.Pdf.FitPageDestination` → `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.FitPageDestination` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed constructor. See [Constructors](./dotnet-interface.mdx#constructors).New method `static FitPageDestination Create(Pdf.Document targetDocument, Pdf.Pagepage, bool fitActualContent)`. See [Creation and copying methods.](./dotnet-interface.mdx#creation-and-copying-methods). See [DirectDestination](#pdftoolspdfdirectdestination) for inherited changes. |
#### PdfTools.Pdf.FitRectangleDestination
| [Class] `PdfTools.Pdf.FitRectangleDestination` → `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.FitRectangleDestination` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed constructor. See [Constructors](./dotnet-interface.mdx#constructors).New method `static FitRectangleDestination Create(Pdf.Document targetDocument, Pdf.Page page, Geometry.Real.Rectangle rectangle)`. See [Creation and copying methods.](./dotnet-interface.mdx#creation-and-copying-methods) See [DirectDestination](#pdftoolspdfdirectdestination) for inherited changes. |
#### PdfTools.Pdf.FitWidthDestination
| [Class] `PdfTools.Pdf.FitWidthDestination` → `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.FitWidthDestination` |
| ----------------------------------------------------------------------------------------------------------------- |
| Removed constructor. See [Constructors](./dotnet-interface.mdx#constructors).
New method `static FitWidthDestination Create(Pdf.Document targetDocument, Pdf.Page page, bool fitActualContent)`. See [Creation and copying methods.](./dotnet-interface.mdx#creation-and-copying-methods). See [DirectDestination](#pdftoolspdfdirectdestination) for inherited changes. |
#### PdfTools.Pdf.InternalLink
| [Class] `PdfTools.Pdf.InternalLink` → `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.InternalLink` |
| --------------------------------------------------------------------------------------------------- |
| See [Link](#pdftoolspdflink) for inherited changes. |
#### PdfTools.Pdf.Link
| [Class] `PdfTools.Pdf.Link` → `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.Link` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Removed inheritance from class `Annotation`. See [Annotations](./dotnet-interface.mdx#annotations).Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](./dotnet-interface.mdx#removal-of-idisposable-implementation).New method `static Link Copy(Pdf.Document targetDocument, Link link)`. See [Creation and copying methods.](./dotnet-interface.mdx#creation-and-copying-methods)Duplicated property `Geometry.Real.Rectangle BoundingBox { get... }` from former base class `Annotation`.Duplicated property `bool Hidden { get... }` from former base class `Annotation`.Duplicated property `bool NoPrint { get... }` from former base class `Annotation`. |
#### PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.LinkList
| [Class] `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.LinkList` |
| ----------------------------------------------------------------- |
| A list that contains [Link](#pdftoolspdflink) objects. |
#### PdfTools.Pdf.LocationZoomDestination
| [Class] `PdfTools.Pdf.LocationZoomDestination` → `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.LocationZoomDestination` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed constructor. See [Constructors](./dotnet-interface.mdx#constructors).New method `static ZoomDestination Create(Pdf.Document targetDocument, Pdf.Page page, double? left, double? top, double? zoom)`. See [Creation and copying methods.](./dotnet-interface.mdx#creation-and-copying-methods). See [DirectDestination] for inherited changes. |
#### PdfTools.Pdf.NamedDestination
| [Class] `PdfTools.Pdf.NamedDestination` → `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.NamedDestination` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static NamedDestination Create(Pdf.Document targetDocument, string name, DirectDestination target)` See [Creation and copying methods.](./dotnet-interface.mdx#creation-and-copying-methods)See [Destination](#pdftoolspdfdestination) for inherited changes. |
#### PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.NamedDestinationCopyStrategy
| [Enum.] `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.NamedDestinationCopyStrategy` |
| ----------------------------------------------------------------------------------------------------------------------------------------- |
| Values:CopyResolveSubstitutes the removed `CopyOption`. See [Copy options](./dotnet-interface.mdx#copy-options). |
#### PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.OutlineCopyOptions
| [Class] `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.OutlineCopyOptions` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| constructor `OutlineCopyOptions()`Property `Pdf.Navigation.NamedDestinationCopyStrategy NamedDestinations { get... set... }` Default: `NamedDestinationCopyStrategy.Copy`Property `bool CopyLogicalStructure { get... set... }` Default: `true`Substitutes the removed `CopyOption`. See [Copy options](./dotnet-interface.mdx#copy-options). |
#### PdfTools.Pdf.OutlineItem
| [Class] `PdfTools.Pdf.OutlineItem` → `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.OutlineItem` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](./dotnet-interface.mdx#removal-of-idisposable-implementation).New method `static OutlineItem Create(Pdf.Document targetDocument, string title, Destination Destination)`. See [Creation and copying methods.](./dotnet-interface.mdx#creation-and-copying-methods)New method `static OutlineItem Copy(Pdf.Document targetDocument, OutlineItem outlineItem, OutlineCopyOptions options)`. See [Creation and copying methods.](./dotnet-interface.mdx#creation-and-copying-methods). See [Copy options](./dotnet-interface.mdx#copy-options). |
#### PdfTools.Pdf.OutlineItemList
| [Class] `PdfTools.Pdf.OutlineItemList` → `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.OutlineItemList` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](./dotnet-interface.mdx#removal-of-idisposable-implementation). |
#### PdfTools.Pdf.PageDisplay
| [Class] `PdfTools.Pdf.PageDisplay[struct]` → `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.PageDisplay` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed type from reference type (class) to value type (struct). See [Value types](./dotnet-interface.mdx#value-types).Changed default value of field `Continuous` from `true` to `false`. |
#### PdfTools.Pdf.PageLayout
| [Enum.] `PdfTools.Pdf.PageLayout`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.PageLayout` |
| ---------------------------------------------------------------------------------------------- |
| |
#### PdfTools.Pdf.ViewerNavigationPane
| [Enum.] `PdfTools.Pdf.ViewerNavigationPane`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.ViewerNavigationPane` |
| ------------------------------------------------------------------------------------------------------------------ |
| |
#### PdfTools.Pdf.ViewerSettings
| [Class] `PdfTools.Pdf.ViewerSettings` → `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.ViewerSettings` |
| ------------------------------------------------------------------------------------------------------- |
| Changed type of property `PageDisplay` from reference type `PageDisplay` to nullable value type `PageDisplay?`.New method `static ViewerSettings Copy(Pdf.Document targetDocument, ViewerSettings viewerSettings)`. See [Creation and copying methods.](./dotnet-interface.mdx#creation-and-copying-methods)
#### PdfTools.Pdf.WebLink
| [Class] `PdfTools.Pdf.WebLink` → `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.WebLink` |
| ----------------------------------------------------------------------------------------- |
| Removed constructor. See [Constructors](./dotnet-interface.mdx#constructors).
New method `static WebLink Create(Pdf.Document targetDocument, Geometry.Real.Rectangle boundingBox, string uri)`. See [Creation and copying methods.](./dotnet-interface.mdx#creation-and-copying-methods). See [Link](#pdftoolspdflink) for inherited changes.|
---
## Java interface changes for PDF Toolbox SDK
There are several changes in naming and behavior in the Java interface to bear in mind when migrating from the the 3-Heights® PDF Toolbox API to the PDF Toolbox SDK.
## Namespaces
The company namespace of PDF Tools AG is `com.pdf_tools`, both in the 3-Heights® PDF Toolbox API and in the PDF Toolbox SDK.
In the 3-Heights® PDF Toolbox API, most interface elements reside in the namespace `com.pdf_tools.pdf`, except for the following type, which reside directly in `com.pdf_tools`:
- Point
- Rectangle
- Size
- ErrorCode
- ErrorCodeException
- FileStream
- MemoryStream
- Stream
The PDF Toolbox SDK introduces the following new namespaces:
| Namespace | Area of usage |
| ------------------------------------------------------- | --------------------------- |
| `com.pdf_tools.fourheights.pdftoolbox` | Base namespace |
| `com.pdf_tools.fourheights.pdftoolbox.geometry` | Geometric related |
| `com.pdf_tools.fourheights.pdftoolbox.geometry.real` | For floating point numbers |
| `com.pdf_tools.fourheights.pdftoolbox.geometry.integer` | For integer numbers |
| `com.pdf_tools.fourheights.pdftoolbox.pdf` | General PDF related |
| `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations` | Annotation related |
| `com.pdf_tools.fourheights.pdftoolbox.pdf.content` | Page content related |
| `com.pdf_tools.fourheights.pdftoolbox.Pdf.Forms` | Form field related |
| `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation` | Document navigation related |
## The Sdk class
### License keys and product version
In the 3-Heights® PDF Toolbox API, the public methods `setLicenseKey` and `getProductVersion` of the common base class `internal.NativeObject` allows setting a license key and querying the version of the API.
In the PDF Toolbox SDK, this functionality has been moved to the class `Sdk`. Specifically:
- `Sdk.initialize` must be called to set a license key. See also [License keys](./README.mdx#license-keys).
- `Sdk.getVersion` gets the API’s version number as a string.
### The PDF Producer entry
In the 3-Heights® PDF Toolbox API, when creating a PDF, the `Metadata` object sets the PDF’s Producer entry via the method `Metadata.setProducer`.
In the PDF Toolbox SDK, the class `pdf.Metadata` has no method `pdf.Metadata.setProducer`. Instead, the Producer entry for all output PDFs is preconfigured as a string consisting of two parts:
1. The first part (the “base” part) is encoded in the license key. Hence, this part is determined when buying a license from Pdftools.
2. The second part (the “suffix” part) is configured when calling `Sdk.initialize` as an argument. It is recommended to use the suffix solely for version information.
The assembled Producer entry can be obtained after calling `Sdk.initialize` using the method `Sdk.getProducerFullName`.
## AutoCloseable implementation removed
In the PDF Toolbox SDK, the implementation of the `AutoCloseable` interface has been removed from all but the following classes:
- `Document`
- `ContentGenerator`
- `TextGenerator`
- `Stream`
Native resources are now released automatically when getting or appending a page.
## Structs extend NativeBase
In the 3-Heights® PDF Toolbox API, interface elements documented as struct are independent Java classes.
In the PDF Toolbox SDK, these structs are still Java classes, but they now extend `com.pdf_tools.fourheights.pdftoolbox.internal.NativeBase`. As a consequence, an attempt to load the native library (if not already loaded) is done when constructing a struct. This is due to the static constructor in this base class.
## Exceptions
In the PDF Toolbox SDK, the `ErrorCodeException` has been renamed to `PdfToolboxException`. The method `ErrorCodeException.getCode` has been removed and substituted by the following new classes, each extending `PdfToolboxException`:
- `ConformanceException`
- `CorruptException`
- `LicenseException`
- `PasswordException`
- `UnknownFormatException`
- `UnsupportedFeatureException`
Instead of an `ErrorCodeException` with method `ErrorCodeException.getErrorCodeErrorCode.IO`, a `java.io.IOException` is generated.
## OffsetDateTime
In the 3-Heights® PDF Toolbox API, class members that represent date and time have a type `java.util.Calendar`.
In the PDF Toolbox SDK, dates and times are represented by the type `java.time.OffsetDateTime`.
This affects the following members:
- `Methodpdf.FileReference.getModificationDate`
- `Methodspdf.Metadata.‹get|set›CreationDate`
- `Methodpdf.Metadata.‹get|set›ModificationDate`
- `Methodpdf.forms.SignatureField.getDate`
## Renaming
Some interface elements have been renamed. The following principles apply:
- Interface elements that include abbreviations are now written consistently in Pascal case. For example `RGB` → is now `Rgb`, except for two-letter abbreviations, which are written as two capital letters, such as`IO`.
- Some abbreviations have been changed to full words, for example `Char` → `Character`.
- Some words that are repeated in the introduced namespace have been dropped. For example, `AnnotationPopup` → is now `pdf.annotations.Popup`.
- Improved clarity, brevity, jargon, and technical correctness.
## Affine transform objects should be initialized
In the 3-Heights® PDF Toolbox API, `Transformation` is a class.
In the PDF Toolbox SDK, this element has been renamed to `geometry.real.AffineTransformation`, and its type has changed to struct. Interface elements documented asstruct are still classes in Java, but they behave a little differently.
Specifically, default constructed `geometry.real.AffineTransform` objects are not valid. (A matrix with all values 0 is singular.) Default constructed `geometry.real.AffineTransform` objects should always be initialized with `geometry.real.AffineTransform.getIdentity`.
For example:
```
AffineTransform transform = AffineTransform.getIdentity();
```
## Creation and copying methods
In the 3-Heights® PDF Toolbox API, most document-associated objects are created in an output document by static methods `Document.create...` and copied from an input document to an output document by static methods `Document.copy...`. For example, `Document.createPage`, `Document.copyPage`.
In the PDF Toolbox SDK, all these methods have been moved from the `Document` class to the class that is created or copied. For example, method `Document.createPage` → `pdf.Page.create`.
This affects the following classes:
- `Page`
- `Image`
- `ImageMask`
- `Font`
- `Group`
- `ColorSpace`
- `Paint`
- `Text`
- `Metadata`
- `FileReference`
- `SubForm`
- `GeneralTextField`
- `CombTextField`
- `CheckBoxField`
- `RadioButtonField`
- `ListBoxField`
- `ComboBoxField`
- `NamedDestination`
- `OutlineItem`
- `Annotation`
- `Link`
- `FileAttachmentAnnotation`
- `FreeTextAnnotation`
- `StickyNoteAnnotation`
- `TextStampAnnotation`
- `CustomStampAnnotation`
- `CircleAnnotation`
- `SquareAnnotation`
- `LineAnnotation`
- `PolyLineAnnotation`
- `PolygonAnnotation`
- `FreeDrawingAnnotation`
- `ContentElement`
- `FormFieldNode`
## Constructors
In the 3-Heights® PDF Toolbox API, some document-associated objects are created by means of a constructor. For example, `FitPageDestination.FitPageDestination`.
In the PDF Toolbox SDK, most of these document-associated objects are now created and copied with static methods `create` and `copy`.
This affects the following classes:
- `EmbeddedPdfLink`
- `FitHeightDestination`
- `FitPageDestination`
- `FitRectangleDestination`
- `FitWidthDestination`
- `LocationZoomDestination`
- `WebLink`
In the PDF Toolbox SDK, the following classes (most of them not document-associated) have constructors:
- `pdf.Encryption`
- `pdf.content.ContentExtractor`
- `pdf.content.ContentGenerator`
- `pdf.content.Fill`
- `pdf.content.PageCopyOptions`
- `pdf.content.PathGenerator`
- `pdf.content.Path`
- `pdf.content.Stroke`
- `pdf.content.TextGenerator`
- `pdf.content.Transparency`
- `pdf.navigation.OutlineCopyOptions`
## Unknown PDF conformance
In the 3-Heights® PDF Toolbox API, the `Conformance` enumeration has a value `Conformance.UNKNOWN`.
The PDF Toolbox SDK enum `pdf.Conformance` has no such value. The handling of unknown (i.e. automatically upgrading) PDF conformance is now done as follows:
- In the method `pdf.Document.create`, the second argument `pdf.Conformance` is allowed to be `null`, where a `null` value has the same meaning as the removed value `Conformance.UNKNOWN`.
- The method `pdf.Document.getConformance` always returns the current conformance. For input documents, this is the claimed conformance. For output documents, this is either the explicit conformance set when creating, or (if created with `null`) the conformance the output PDF would have if closed now.
## Copy options
In the 3-Heights® PDF Toolbox API, page copying and outline copying behavior is configurable by means of the `CopyOption`enum.
In the PDF Toolbox SDK, this enum has been substituted by new classes:
- `pdf.PageCopyOptionsUsed` in methods `pdf.Page.copy` and `pdf.Group.createFromPage`.
- `pdf.navigation.OutlineCopyOptionsUsed` in method `pdf.navigation.OutlineItem.copy`.
Each copying configuration decision is reflected in a class member. Apart from boolean for on-off decisions, the following enumerations model possible choices:
- `pdf.CopyStrategy`
- `pdf.RemovalStrategy`
- `pdf.NameConflictResolution`
- `pdf.forms.FormFieldCopyStrategy`
- `pdf.navigation.NamedDestinationCopyStrategy`
This clarifies the copying behavior and allows sensible default values.
## Color space classes
**Class hierarchy**
In the 3-Heights® PDF Toolbox API, there is a single class `ColorSpace`, which covers all types of color spaces.
In the PDF Toolbox SDK, the `ColorSpaceType` enumeration and the method `ColorSpace.getType` have been removed. Instead, there are the following new classes, all extending `pdf.content.ColorSpace`:
- `pdf.content.CalibratedGrayColorSpace`
- `pdf.content.CalibratedRgbColorSpace`
- `pdf.content.DeviceCmykColorSpace`
- `pdf.content.DeviceGrayColorSpace`
- `pdf.content.DeviceRgbColorSpace`
- `pdf.content.IccBasedColorSpace`
- `pdf.content.IndexedColorSpace`
- `pdf.content.LabColorSpace`
- `pdf.content.NChannelColorSpace`
- `pdf.content.SeparationColorSpace`
The 3-Heights® PDF Toolbox API color space type `DeviceN` now is subsumed by the more general `pdf.content.NChannelColorSpace`.
**Device color spaces versus process color spaces**
In the 3-Heights® PDF Toolbox API, the method `Document.createDeviceColorSpace` does not necessarily create a device color space, e.g., in case of PDF/A.
In the PDF Toolbox SDK, the enumeration `DeviceColorSpaceType` has been renamed to `pdf.content.ProcessColorSpaceType`. The class `pdf.content.ColorSpace` now has the following static method:
```
pdf.content.ColorSpaceCreateProcessColorSpace(pdf.DocumenttargetDocument, pdf.content.DeviceColorSpaceType type)
```
This method creates either a device color space, or, in case of PDF/A, a calibrated (grayscale or RGB) or an ICC-based(CMYK) color space.
## Embedded/Associated/Attached files
In the 3-Heights® PDF Toolbox API, embedded files, associated files, and files contained in a `FileAttachmentAnnotation` are jointly listed in the method `Document.getEmbeddedFiles`.
In the PDF Toolbox SDK, embedded files, associated files, and files contained in file attachment annotations are treated separately. A `pdf.Document` now has two lists for appending:
- `pdf.Document.getAssociatedFiles`
- `pdf.Document.getPlainEmbeddedFiles`
The former method `Document.getEmbeddedFiles` has been renamed to `pdf.Document.getAllEmbeddedFiles`, a read-only list that contains embedded files and files contained in `pdf.annotations.FileAttachment` annotations. This list is equivalent to what a viewer normally lists in an embedded files pane. For example, the Attachments pane in the Adobe PDF viewer.
## Annotations
In the PDF Toolbox SDK, the following annotation classes have been renamed for technical correctness:
- `FreeDrawingAnnotation` → `pdf.annotations.InkAnnotation`
- `CircleAnnotation` → `pdf.annotations.EllipseAnnotation`
- `SquareAnnotation` → `pdf.annotations.RectangleAnnotation`
The methods `RadioButtenField.getCanToggleOff` and `RadioButtenField.setCanToggleOff` have been removed. In most PDF viewers, there is no support for this feature.
**Class hierarchy**
In the 3-Heights® PDF Toolbox API, `Widget` and `Link` extend the base class `Annotation`.
In the PDF Toolbox SDK, the classes `pdf.forms.Widget` and `pdf.navigation.Link` have been separated from their former base class. Due to this separation:
- A `pdf.Page` now has the following lists:
- `pdf.Page.getAnnotations`
- `pdf.Page.getLinks`
- `pdf.Page.getFormFieldWidgets`
- The following methods of `pdf.annotations.Annotation` have been replicated in `pdf.forms.Widget` and `pdf.navigation.Link`:
- `getBoundingBox`
- `getHidden`
- `getNoPrint`
The intermediate base classes `PolyDrawingAnnotation` and `ShapeDrawingAnnotation` have been removed. All drawing annotations now directly extend the class `pdf.annotations.DrawingAnnotation`. Those drawing annotations that have a closed path (`pdf.annotations.PolygonAnnotation`, `pdf.annotations.EllipseAnnotation`, `pdf.annotations.RectangleAnnotation`) have methods `getFill` and `setFill`.
**Class hierarchy comparison**
| 3-Heights® PDF Toolbox (left) | PDF Toolbox SDK (right) |
| ----------------------------- | ----------------------- |
## MaxLength in text fields
In the 3-Heights® PDF Toolbox API, the error behavior of the method `TextField.setMaxLength` depends on the actual underlying class: `GeneralTextField` allows `null` values, while `CombTextField` does not.
In the PDF Toolbox SDK, the methods `TextField.getMaxLength` and `TextField.setMaxLength` have been removedand replicated in the derived classes `pdf.forms.CombTextField` and `pdf.forms.GeneralTextField`, in the latter as a nullable `Integer`.
## Unified paint creation
In the 3-Heights® PDF Toolbox API, there exist three methods for creating a `Paint` object:
- `Document.createSolidPaint`
- `Document.createAlphaPaint`
- `Document.createBlendingPaint`
In the PDF Toolbox SDK, these methods have been replaced by a single static method `pdf.content.Paint.create`. See also [Creation and copying methods](#creation-and-copying-methods).
## Separate inside rule from path
In the 3-Heights® PDF Toolbox API, the constructor `Path.Path` has an argument `InsideRule rule`.
In the PDF Toolbox SDK, this argument is dropped. Instead, the `InsideRule` now is specified in a new member of `pdf.content.Fill` when painting the path with `pdf.content.ContentGenerator.paintPath`, or it is specified ina method argument when clipping with `pdf.content.ContentGenerator.clipWithPath`. This removes ambiguity and allows a separated treatment of the inside rule for path filling and path clipping.
## Path and text clipping operations
In the 3-Heights® PDF Toolbox API, the `ContentGenerator` supports simultaneous clipping and painting operations.
In the PDF Toolbox SDK, path and text clipping operations have been separated from path and text painting operations as follows:
- The argument `boolean intersectClipPath` has been removed from the method `ContentGenerator.paintPath`.
- The method `TextGenerator.setRendering` has been removed (see also [Text generator](#text-generator)), and its argument `boolean intersectClipping` has been dropped without a replacement.
- The new class `pdf.content.ContentGenerator` has two new methods for path and text clipping operations:
- `pdf.content.ContentGenerator.clipWithPath`
- `pdf.content.ContentGenerator.clipWithText`
To achieve the same effect of simultaneous clipping and painting, the painting operation has to precede the clipping operation.
## Text generator
In the PDF Toolbox SDK, the method `TextGenerator.setRendering` has been substituted by two separate methods:
- `pdf.content.TextGenerator.setFill`
- `pdf.content.TextGenerator.setStroke`
## Image size and image mask size
In the 3-Heights® PDF Toolbox API, `Image` and `ImageMask` have methods `getWidth` and `getHeight`.
In the PDF Toolbox SDK, these are substituted by methods `pdf.content.Image.getSize` and `pdf.content.ImageMask.getSize`, both of which have the new type `geometry.integer.Size`.
---
## Reference
For all changes in the Java interface between 3-Heights® PDF Toolbox API and the PDF Toolbox SDK, see [Java Reference](java-reference.mdx).
---
## Reference for changes in Java interface
This section lists all changes in the Java interface between 3-Heights® PDF Toolbox API and the PDF Toolbox SDK. Interface elements are ordered alphabetically by PDF Toolbox SDK namespace.
:::info
For the full API reference for the PDF Toolbox SDK, see [Java API reference](https://api-reference.pdf-tools.com/toolsdk/4.3/javadoc/index.html?overview-summary.html).
:::
#### com.pdf_tools.internal.NativeObject
| [Class] `com.pdf_tools.internal.NativeObject` → `com.pdf_tools.fourheights.pdftoolbox.internal.NativeObject` |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed static method `setLicenseKey`.Removed static method `checkLicense`.Removed static method `getProductVersion`. The above have been substituted by new static members in [Sdk](#compdf_toolsfourheightspdftoolboxsdk). |
## Base namespace
#### com.pdf_tools.fourheights.pdftoolbox.ConformanceException
| [Class] `com.pdf_tools.fourheights.pdftoolbox.ConformanceException` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`PdfToolboxException`](#compdf_toolserrorcodeexception).Substitutes the removed method `ErrorCodeException.getCode` with value `ErrorCode.CONFORMANCE`. See [Exceptions](./java-interface.mdx#exceptions). |
#### com.pdf_tools.fourheights.pdftoolbox.CorruptException
| [Class] `com.pdf_tools.fourheights.pdftoolbox.CorruptException` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Extends [PdfToolboxException](#compdf_toolserrorcodeexception). Substitutes the removed method `ErrorCodeException.getCode` with value `ErrorCode.CORRUPT`. See [Exceptions](./java-interface.mdx#exceptions). |
#### com.pdf_tools.ErrorCode
| [Enum.] `com.pdf_tools.ErrorCode` → `com.pdf_tools.fourheights.pdftoolbox.ErrorCode` |
| ------------------------------------------------------------------------------------ |
| Removed. See [Exceptions](./java-interface.mdx#exceptions). |
#### com.pdf_tools.ErrorCodeException
| [Class] `com.pdf_tools.ErrorCodeException`→ `com.pdf_tools.fourheights.pdftoolbox.PdfToolboxException` |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed method `getCode`. In all affected methods, the `ErrorCodeExceptionwithErrorCode.IO` has been substituted by a `java.io.IOException`. See [Exceptions](./java-interface.mdx#exceptions). |
#### com.pdf_tools.fourheights.pdftoolbox.LicenseException
| [Class] `com.pdf_tools.fourheights.pdftoolbox.LicenseException` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Extends [PdfToolboxException](#compdf_toolserrorcodeexception). Substitutes the removed method `ErrorCodeException.getCode` with value `ErrorCode.LICENSE`. See [Exceptions](./java-interface.mdx#exceptions). |
#### com.pdf_tools.fourheights.pdftoolbox.PasswordException
| [Class] `com.pdf_tools.fourheights.pdftoolbox.PasswordException` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [PdfToolboxException](#compdf_toolserrorcodeexception). Substitutes the removed method `ErrorCodeException.getCode` with value `ErrorCode.PASSWORD`. See [Exceptions](./java-interface.mdx#exceptions). |
#### com.pdf_tools.fourheights.pdftoolbox.Sdk
| [Class] `com.pdf_tools.fourheights.pdftoolbox.Sdk` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Method `static boolean initialize(String license, String producerSuffix)`Method `static String getVersion()``static String getProducerFullName()`See [The Sdk class](./java-interface.mdx#the-sdk-class). |
#### com.pdf_tools.pdf.StringMap
| [Class] `com.pdf_tools.pdf.StringMap`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.StringMap` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [AutoCloseable implementation removed](./java-interface.mdx#autocloseable-implementation-removed). |
#### com.pdf_tools.fourheights.pdftoolbox.UnknownFormatException
| [Class] `com.pdf_tools.fourheights.pdftoolbox.UnknownFormatException` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [PdfToolboxException](#compdf_toolserrorcodeexception). Substitutes the removed method `ErrorCodeException.getCode` with value `ErrorCode.UNKNOWN_FORMAT`. See [Exceptions](./java-interface.mdx#exceptions). |
#### com.pdf_tools.fourheights.pdftoolbox.UnsupportedFeatureException
| [Class] `com.pdf_tools.fourheights.pdftoolbox.UnsupportedFeatureException` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Extends [PdfToolboxException](#compdf_toolserrorcodeexception). Substitutes the removed method `ErrorCodeException.getCode` with value `ErrorCode.UNSUPPORTED_FEATURE`. See [Exceptions](./java-interface.mdx#exceptions). |
## geometry namespace
#### com.pdf_tools.pdf.Rotation
| [Enum.] `com.pdf_tools.pdf.Rotation` → `com.pdf_tools.fourheights.pdftoolbox.geometry.Rotation` |
| ----------------------------------------------------------------------------------------------- |
| Renamed enum value `NO_ROTATION` → `NONE`. |
#### com.pdf_tools.pdf.TextAlignment
| [Enum.] `com.pdf_tools.pdf.TextAlignment` → `com.pdf_tools.fourheights.pdftoolbox.geometry.HorizontalAlignment` |
| --------------------------------------------------------------------------------------------------------------- |
| |
### pdf.geometry.integer namespace
#### com.pdf_tools.fourheights.pdftoolbox.geometry.integer.Size
| [Struct] `com.pdf_tools.fourheights.pdftoolbox.geometry.integer.Size` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `intWidth``intHeight` Used in [`Image`](#compdf_toolspdfimage) and [`ImageMask`](#compdf_toolspdfimagemask) to substitute the removed methods `Image.getWidth`, `Image.getHeight`, `ImageMask.getWidth`, and `ImageMask.getHeight`. See [Image size and image mask size](./java-interface.mdx#image-size-and-image-mask-size). |
### geometry.real namespace
#### com.pdf_tools.Point
| [Struct] `com.pdf_tools.Point`→ `com.pdf_tools.fourheights.pdftoolbox.geometry.real.Point` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New base class `com.pdf_tools.fourheights.pdftoolbox.internal.NativeBase`. See [Structs extend NativeBase](./java-interface.mdx#structs-extend-nativebase). |
#### com.pdf_tools.Rectangle
| [Struct] `com.pdf_tools.Rectangle`→ `com.pdf_tools.fourheights.pdftoolbox.geometry.real.Rectangle` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New base classcom.pdf_tools.fourheights.pdftoolbox.internal.NativeBase. See [Structs extend NativeBase](./java-interface.mdx#structs-extend-nativebase).Removed method `getWidth`.Removed method `getHeight`.Removed method `getSize`.Removed method `getLeftBottom`.Removed method `getLeftTop`.Removed method `getRightBottom`.Removed method `getRightTop`.Removed method `getCenter`. |
#### com.pdf_tools.Size
| [Struct] `com.pdf_tools.Size`→ `com.pdf_tools.fourheights.pdftoolbox.geometry.real.Size` |
| -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New base `classcom.pdf_tools.fourheights.pdftoolbox.internal.NativeBase`. See [Structs extend NativeBase](./java-interface.mdx#structs-extend-nativebase). |
#### com.pdf_tools.pdf.Transformation
| [Class → Struct] `com.pdf_tools.pdf.Transformation` → `com.pdf_tools.fourheights.pdftoolbox.geometry.real.AffineTransform` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [AutoCloseable implementation removed](./java-interface.mdx#autocloseable-implementation-removed). Removed `copy` constructor.Changed behavior of default constructor. Now returns an `invalidAffineTransform` object with all fieldsdefault initialized to `0`. Use method `getIdentity` to obtain a valid object. See [Affine transform objects should be initialized](./java-interface.mdx#affine-transform-objects-should-be-initialized).Removed method `rotate`.Renamed method `rotateAround` → `rotate`.New fields:`double a``double b``double c``double d``double e``double f`New method `static AffineTransform getIdentity()`. See [Affine transform objects should be initialized](./java-interface.mdx#affine-transform-objects-should-be-initialized). |
## pdf namespace
#### com.pdf_tools.pdf.Conformance
| [Enum.] `com.pdf_tools.pdf.Conformance` → `com.pdf_tools.fourheights.pdftoolbox.pdf.Conformance` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed enum value `UNKNOWN`. See [Unknown PDF conformance.](./java-interface.mdx#unknown-pdf-conformance).Renamed remaining enum values: `PDF_1_0` → `PDF10``PDF_1_1` → `PDF11``PDF_1_2` → `PDF12``PDF_1_3` → `PDF13``PDF_1_4` → `PDF14``PDF_1_5` → `PDF15``PDF_1_6` → `PDF16``PDF_1_7` → `PDF17``PDF_2_0` → `PDF20``PDFA_1B` → `PDF_A1_B``PDFA_1A` → `PDF_A1_A``PDFA_2B` → `PDF_A2_B``PDFA_2U` → `PDF_A2_U``PDFA_2A` → `PDF_A2_A``PDFA_3B` → `PDF_A3_B``PDFA_3U` → `PDF_A3_U``PDFA_3A` → `PDF_A3_A` |
#### com.pdf_tools.pdf.CopyOption
| [Enum.] `com.pdf_tools.pdf.CopyOption` |
| --------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed. Substituted by [`pdf.PageCopyOptions`] and `pdf.navigation.OutlineCopyOptions`. See [Copy options](./java-interface.mdx#copy-options). |
#### com.pdf_tools.fourheights.pdftoolbox.pdf.CopyStrategy
| [Enum.] `com.pdf_tools.fourheights.pdftoolbox.pdf.CopyStrategy` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Values:`COPY``FLATTEN``REMOVE`Substitutes the removed `CopyOption`. See [Copy options](./java-interface.mdx#copy-options). |
#### com.pdf_tools.pdf.Document
| [Class] `com.pdf_tools.pdf.Document`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.Document` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed method `getOutlineItems` → `getOutline`.Changed return and argument type of methods `getOutputIntent` and `setOutputIntent` from `ColorSpace` to `pdf.content.IccBasedColorSpace`. See [Color space classes](./java-interface.mdx#color-space-classes).Renamed method `getEmbeddedFiles` → `getAllEmbeddedFiles`.Appending is not supported anymore. This is a read-only list of all embedded files and all files in `FileAttachmentAnnotation`. See [Embedded/Associated/Attached files.](./java-interface.mdx#embeddedassociatedattached-files).Changed behavior of method `getConformance` for output documents: Always returns the current conformance instead of `removedConformance.UNKNOWN`.Changed behavior of method `create`: For the second argument of type `Conformance`, `null` is now legal. See [Unknown PDF conformance.](./java-interface.mdx#unknown-pdf-conformance).Removed and substituted the following methods: `createFileReference` → `pdf.FileReference.create``createMetadata` → `pdf.Metadata.create``createPage` → `pdf.Page.create``createCircleAnnotation` → `pdf.annotations.EllipseAnnotation.create``createCustomStampAnnotation` → `pdf.annotations.CustomStamp.create``createFileAttachmentAnnotation` → `pdf.annotations.FileAttachment.create``createFreeDrawingAnnotation` → `pdf.annotations.InkAnnotation.create``createFreeTextAnnotation` → `pdf.annotations.FreeText.create``createLineAnnotation` → `pdf.annotations.LineAnnotation.create``createPolyLineAnnotation` → `pdf.annotations.PolyLineAnnotation.create``createPolygonAnnotation` → `pdf.annotations.PolygonAnnotation.create``createSquareAnnotation` → `pdf.annotations.RectangleAnnotation.create``createStickyNoteAnnotation` → `pdf.annotations.StickyNote.create``createTextStampAnnotationRaw` → `pdf.annotations.TextStamp.createRaw``createAlphaPaint, createBlendingPaint, createSolidPaint` → `pdf.content.Paint.create`. See [Unified paint creation](./java-interface.mdx#unified-paint-creation).`createDeviceColorSpace` → `pdf.content.ColorSpace.createProcessColorSpace``createFont` → `pdf.content.Font.create``createGroup` → `pdf.content.Group.create``createICCColorSpace` → `pdf.content.IccBasedColorSpace.create``createImageMask` → `pdf.content.ImageMask.create``createImage` → `pdf.content.Image.create``createSystemFont` → `pdf.content.Font.createFromSystem``createText` → `pdf.content.Text.create``createCheckBoxField` → `pdf.forms.CheckBoxField.create``createCombTextField` → `pdf.forms.CombTextField.create``createComboBoxField` → `pdf.forms.ComboBoxField.create``createGeneralTextField` → `pdf.forms.GeneralTextField.create``createListBoxField` → `pdf.forms.ListBoxField.create``createRadioButtonField` → `pdf.forms.RadioButtonField.create``createSubForm` → `pdf.forms.SubForm.create``createNamedDestination` → `pdf.navigation.NamedDestination.create``createOutlineItem` → `pdf.navigation.OutlineItem.create``copyFileReference` → `pdf.FileReference.copy``copyMetadata` → `pdf.Metadata.copy``copyPage` → `pdf.Page.copy``copyAnnotation` → `pdf.annotations.Annotation.copy``copyColorSpace` → `pdf.content.ColorSpace.copy``copyContentElement` → `pdf.content.ContentElement.copy``copyGroupElementWithoutContent` → `pdf.content.GroupElement.copyWithoutContent``copyPageAsGroup` → `pdf.content.Group.copyFromPage``copyFormFieldNode` → `pdf.forms.FormFieldNode.copy``copyViewerSettings` → `pdf.navigation.ViewerSettings.copy``copyOutlineItem` → `pdf.navigation.OutlineItem.copy` See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods).New method `pdf.FileReferenceList getPlainEmbeddedFiles()`. This is a list of all embedded files that are neither associated nor contained in a `FileAttachmentAnnotation`. See [Embedded/Associated/Attached files](./java-interface.mdx#embeddedassociatedattached-files). |
#### com.pdf_tools.pdf.EncryptionParams
| [Struct → Class] `com.pdf_tools.pdf.EncryptionParams` → `com.pdf_tools.fourheights.pdftoolbox.pdf.Encryption` |
| ------------------------------------------------------------------------------------------------------------- |
| New constructor `Encryption(String userPassword, String ownerPassword, Permission permissions)`. |
#### com.pdf_tools.pdf.FileReference
| [Class] `com.pdf_tools.pdf.FileReference`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.FileReference` |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [AutoCloseable implementation removed](./java-interface.mdx#autocloseable-implementation-removed)Changed type of method `get ModificationDate` from `java.util.Calendar` to `java.time.OffsetDateTime.SeeOffsetDateTime`.New method `static FileReference create(Document targetDocument, sys.Streamdata, String name, String mediaType, String description, java.time.OffsetDateTime modificationDate)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods).New method `static FileReference copy(Document targetDocument, FileReference fileReference)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). |
#### com.pdf_tools.pdf.FileReferenceList
| [Class] `com.pdf_tools.pdf.FileReferenceList`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.FileReferenceList` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Removed implementation of the `AutoCloseable` interface. See [AutoCloseable implementation removed](./java-interface.mdx#autocloseable-implementation-removed) |
#### com.pdf_tools.pdf.Metadata
| [Class] `com.pdf_tools.pdf.Metadata`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.Metadata` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [AutoCloseable implementation removed](./java-interface.mdx#autocloseable-implementation-removed)Removed method `setProducer`. See [The PDF Producer entry](./java-interface.mdx#the-pdf-producer-entry).Changed type of methods `getCreationDate` and `setCreationDate` from `java.util.Calendar` to `java.time.OffsetDateTime`. See [OffsetDateTime](./java-interface.mdx#offsetdatetime).Changed type of method `getModificationDate` from `java.util.Calendar` to `java.time.OffsetDateTime`. See [OffsetDateTime](./java-interface.mdx#offsetdatetime).New method `static Metadata create(Document targetDocument, sys.Stream xmp)` See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods).New method `static Metadata copy(Document targetDocument, Metadata metadata)` See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). |
#### com.pdf_tools.fourheights.pdftoolbox.pdf.NameConflictResolution
| [Enum.] `com.pdf_tools.fourheights.pdftoolbox.pdf.NameConflictResolution` |
| ------------------------------------------------------------------------------------------------------------------------------------------- |
| Values:`MERGE``RENAME`Substitutes the removed `CopyOption`. See [Copy options](./java-interface.mdx#copy-options). |
#### com.pdf_tools.pdf.Page
| [Class] `com.pdf_tools.pdf.Page`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.Page` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [AutoCloseable implementation removed](./java-interface.mdx#autocloseable-implementation-removed) Renamed method `crop` → `updateSize`.New method `pdf.forms.WidgetList getFormFieldWidgets()`. See [Annotations](./java-interface.mdx#annotations).New method `pdf.navigation.LinkList getLinks()`. See [Annotations](./java-interface.mdx#annotations).New method `static Page create(Document targetDocument, geometry.real.Size size)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods).New method `static Page copy(Document targetDocument, Page page, PageCopyOptions options)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). |
#### com.pdf_tools.fourheights.pdftoolbox.pdf.PageCopyOptions
| [Class] `com.pdf_tools.fourheights.pdftoolbox.pdf.PageCopyOptions` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Members: Constructor `PageCopyOptions()`Methods `pdf.CopyStrategy getLinks()` and `void setLinks(pdf.CopyStrategy Links)` Default: `CopyStrategy.COPY`Methods `pdf.forms.FormFieldCopyStrategy getFormFields()` and `void setFormFields(pdf.forms.FormFieldCopyStrategy FormFields)` Default: `FormFieldCopyStrategy.COPY`Methods `pdf.CopyStrategy getSignedSignatures()` and `void setSignedSignatures(pdf.CopyStrategy SignedSignatures)` Default: `CopyStrategy.COPY`Methods `pdf.CopyStrategy getAnnotations()` and `void setAnnotations(pdf.CopyStrategy Annotations)` Default: `CopyStrategy.COPY`Methods `boolean getCopyOutlineItems()` and `void setCopyOutlineItems(boolean CopyOutlineItems)`Default: `true`Methods `boolean getCopyAssociatedFiles()` and `void setCopyAssociatedFiles(boolean CopyAssociatedFiles)`Default: `true`Methods `boolean getCopyLogicalStructure()` and `void setCopyLogicalStructure(boolean CopyLogicalStructure)`Default: `true`Methods `pdf.NameConflictResolution getFormField ConflictResolution()` and `void setFormFieldConflictResolution(pdf.NameConflictResolution FormFieldConflictResolution)`Default: `NameConflictResolution.MERGE`Methods `pdf.navigation.NamedDestinationCopyStrategy getNamedDestinations()` and `void setNamedDestinations(pdf.navigation.NamedDestinationCopyStrategy NamedDestinations)`Default: `NamedDestinationCopyStrategy.COPY`Methods `boolean getOptimizeResources()` and `void setOptimizeResources(boolean OptimizeResources)`Default: `true` Substitutes the `removedCopyOption`. See [Copy options](./java-interface.mdx#copy-options). |
#### com.pdf_tools.pdf.PageList
| [Class] `com.pdf_tools.pdf.PageList`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.PageList` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Removed implementation of the `AutoCloseable` interface. See [AutoCloseable implementation removed](./java-interface.mdx#autocloseable-implementation-removed) |
#### com.pdf_tools.pdf.Permission
| [Enum.] `com.pdf_tools.pdf.Permission` → `com.pdf_tools.fourheights.pdftoolbox.pdf.Permission` |
| ---------------------------------------------------------------------------------------------- |
| |
#### com.pdf_tools.fourheights.pdftoolbox.pdf.RemovalStrategy
| [Enum.] `com.pdf_tools.fourheights.pdftoolbox.pdf.RemovalStrategy` |
| ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Values:`FLATTEN` `REMOVE`Substitutes the removed `CopyOption`. See [Copy options](./java-interface.mdx#copy-options). |
### pdf.annotations namespace
#### com.pdf_tools.pdf.Annotation
| [Class] `com.pdf_tools.pdf.Annotation`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.Annotation` |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [AutoCloseable implementation removed](./java-interface.mdx#autocloseable-implementation-removed)Renamed method `getRectangle` → `getBoundingBox`.Removed method `getDoPrint`.New method `getNoPrint` with reversed meaning of the removed method `getDoPrint`.New method `static Annotationcopy(pdf.Document targetDocument, Annotation annotation)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [Annotations](./java-interface.mdx#annotations). |
#### com.pdf_tools.pdf.AnnotationLineEnding
| [Enum.] `com.pdf_tools.pdf.AnnotationLineEnding` → `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.LineEnding` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed enum value `REVERSED_OPEN_ARROW` → `OPEN_ARROW_TAIL`.Renamed enum value `REVERSED_CLOSED_ARROW` → `CLOSED_ARROW_TAIL`. |
#### com.pdf_tools.pdf.AnnotationList
| [Class] `com.pdf_tools.pdf.AnnotationList`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.AnnotationList` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Removed implementation of the `AutoCloseable` interface. See [AutoCloseable implementation removed](./java-interface.mdx#autocloseable-implementation-removed) |
#### com.pdf_tools.pdf.AnnotationPopup
| [Class] `com.pdf_tools.pdf.AnnotationPopup`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.Popup` |
| --------------------------------------------------------------------------------------------------------- |
| Renamed method `getRectangle` → `getBoundingBox`. |
#### com.pdf_tools.pdf.CircleAnnotation
| [Class] `com.pdf_tools.pdf.CircleAnnotation`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.EllipseAnnotation` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed base class to class `DrawingAnnotation`. See [Annotations](./java-interface.mdx#annotations). New method `static EllipseAnnotation create(pdf.Document targetDocument, geometry.real.Rectangle boundingBox, pdf.content.Stroke stroke, pdf.content.Paint fill)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods).New method `pdf.content.Paint getFill()`. See [DrawingAnnotation](#compdf_toolspdfdrawingannotation) for inherited changes. |
#### com.pdf_tools.pdf.CustomStampAnnotation
| [Class] `com.pdf_tools.pdf.CustomStampAnnotation`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.CustomStamp` |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static CustomStampAnnotation create(pdf.Document targetDocument, geometry.real.Rectangle boundingBox)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [StampAnnotation](#compdf_toolspdfstampannotation) for inherited changes. |
#### com.pdf_tools.pdf.DrawingAnnotation
| [Class] `com.pdf_tools.pdf.DrawingAnnotation`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.DrawingAnnotation` |
| ----------------------------------------------------------------------------------------------------------------------- |
| See [MarkupAnnotation](#compdf_toolspdfmarkupannotation) for inherited changes. |
#### com.pdf_tools.pdf.FileAttachmentAnnotation
| [Class] `com.pdf_tools.pdf.FileAttachmentAnnotation`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.FileAttachment` |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static FileAttachmentAnnotation create(pdf.Document targetDocument, geometry.real.Point topleft, pdf.FileReference attachedFile, pdf.content.Pain tpaint)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [MarkupAnnotation](#compdf_toolspdfmarkupannotation) for inherited changes. |
#### com.pdf_tools.pdf.FileAttachmentIcon
| [Enum.] `com.pdf_tools.pdf.FileAttachmentIcon` → `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.FileAttachmentIcon` |
| -------------------------------------------------------------------------------------------------------------------------- |
| |
#### com.pdf_tools.pdf.FreeDrawingAnnotation
| [Class] `com.pdf_tools.pdf.FreeDrawingAnnotation`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.InkAnnotation` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed base class to class `DrawingAnnotation`. See [Annotations](./java-interface.mdx#annotations).New method `static InkAnnotation create(pdf.Document targetDocument, pdf.content.Path path, pdf.content.Stroke stroke)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [DrawingAnnotation](#compdf_toolspdfdrawingannotation) for inherited changes. |
#### com.pdf_tools.pdf.FreeTextAnnotation
| [Class] `com.pdf_tools.pdf.FreeTextAnnotation`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.FreeText` |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static FreeText create(pdf.Document targetDocument, geometry.real.Rectangle boundingBox, String content, pdf.content.Paint paint)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [MarkupAnnotation](#compdf_toolspdfmarkupannotation) for inherited changes. |
#### com.pdf_tools.pdf.HighlightAnnotation
| [Class] `com.pdf_tools.pdf.HighlightAnnotation`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.Highlight` |
| ----------------------------------------------------------------------------------------------------------------- |
| See [TextMarkupAnnotation](#compdf_toolspdftextmarkupannotation) for inherited changes. |
#### com.pdf_tools.pdf.LineAnnotation
| [Class] `com.pdf_tools.pdf.LineAnnotation`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.LineAnnotation` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static LineAnnotation create(pdf.Document targetDocument, geometry.real.Point start, geometry.real.Point end, pdf.content.Stroke stroke)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [DrawingAnnotation](#compdf_toolspdfdrawingannotation) for inherited changes. |
##### com.pdf_tools.pdf.MarkupAnnotation
| [Class] `com.pdf_tools.pdf.MarkupAnnotation`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.MarkupAnnotation` |
| --------------------------------------------------------------------------------------------------------------------- |
| See [Annotation](#compdf_toolspdfannotation) for inherited changes. |
#### com.pdf_tools.pdf.MarkupInfo
| [Class] `com.pdf_tools.pdf.MarkupInfo`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.MarkupInfo` |
| --------------------------------------------------------------------------------------------------------- |
| |
#### com.pdf_tools.pdf.MarkupInfoList
| [Class] `com.pdf_tools.pdf.MarkupInfoList`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.MarkupInfoList` |
| ----------------------------------------------------------------------------------------------------------------- |
| |
#### com.pdf_tools.pdf.PolyDrawingAnnotation
| [Class] `com.pdf_tools.pdf.PolyDrawingAnnotation` |
| ---------------------------------------------------------- |
| Removed. See[Annotations](./java-interface.mdx#annotations). |
#### com.pdf_tools.pdf.PolyLineAnnotation
| [Class] `com.pdf_tools.pdf.PolyLineAnnotation`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.PolyLineAnnotation` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed base class to class [`DrawingAnnotation`](#compdf_toolspdfdrawingannotation). See [Annotations](./java-interface.mdx#annotations).New method `static PolyLineAnnotation create(pdf.Document targetDocument, pdf.content.Path path, pdf.content.Stroke stroke)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [DrawingAnnotation](#compdf_toolspdfdrawingannotation) for inherited changes. |
#### com.pdf_tools.pdf.PolygonAnnotation
| [Class] `com.pdf_tools.pdf.PolygonAnnotation`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.PolygonAnnotation` |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed base class to class [`DrawingAnnotation`](#compdf_toolspdfdrawingannotation). See [Annotations](./java-interface.mdx#annotations).New method `static PolygonAnnotationcreate(pdf.Document targetDocument, pdf.content.Path path, pdf.content.Stroke stroke)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [DrawingAnnotation](#compdf_toolspdfdrawingannotation) for inherited changes. |
#### com.pdf_tools.pdf.ShapeDrawingAnnotation
| [Class] `com.pdf_tools.pdf.ShapeDrawingAnnotation` |
| ----------------------------------------------------------- |
| Removed. See [Annotations](./java-interface.mdx#annotations). |
#### com.pdf_tools.pdf.SquareAnnotation
| [Class] `com.pdf_tools.pdf.SquareAnnotation`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.RectangleAnnotation` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed base class to class [`DrawingAnnotation`](#compdf_toolspdfdrawingannotation). See [Annotations](./java-interface.mdx#annotations).New method `static PolylineAnnotationcreate(pdf.Document targetDocument ,geometry.real.Rectangle boundingBox, pdf.content.Stroke stroke, pdf.content.Fill fill)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods).New method `pdf.content.Fill getFill()`. See [DrawingAnnotation](#compdf_toolspdfdrawingannotation) for inherited changes. |
#### com.pdf_tools.pdf.SquigglyAnnotation
| [Class] `com.pdf_tools.pdf.SquigglyAnnotation`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.Squiggly` |
| --------------------------------------------------------------------------------------------------------------- |
| See [HighlightAnnotation](#compdf_toolspdfhighlightannotation) for inherited changes. |
#### com.pdf_tools.pdf.StampAnnotation
| [Class] `com.pdf_tools.pdf.StampAnnotation`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.Stamp` |
| --------------------------------------------------------------------------------------------------------- |
| See [MarkupAnnotation](#compdf_toolspdfmarkupannotation) for inherited changes. |
#### com.pdf_tools.pdf.StickyNoteAnnotation
| [Class] `com.pdf_tools.pdf.StickyNoteAnnotation`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.StickyNote` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static StickyNotecreate(pdf.Document targetDocument, geometry.real.Point topleft, String content, pdf.content.Paint paint)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [MarkupAnnotation](#compdf_toolspdfmarkupannotation) for inherited changes. |
#### com.pdf_tools.pdf.StrikeThroughAnnotation
| [Class] `com.pdf_tools.pdf.StrikeThroughAnnotation`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.StrikeThrough` |
| ------------------------------------------------------------------------------------------------------------------------- |
| See [TextMarkupAnnotation](#compdf_toolspdftextmarkupannotation) for inherited changes. |
#### com.pdf_tools.pdf.TextInsertAnnotation
| [Class] `com.pdf_tools.pdf.TextInsertAnnotation`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.TextInsert` |
| ------------------------------------------------------------------------------------------------------------------- |
| See [TextMarkupAnnotation](#compdf_toolspdftextmarkupannotation) for inherited changes. |
#### com.pdf_tools.pdf.TextMarkupAnnotation
| [Class] `com.pdf_tools.pdf.TextMarkupAnnotation`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.TextMarkup` |
| ------------------------------------------------------------------------------------------------------------------- |
| See [MarkupAnnotation](#compdf_toolspdfmarkupannotation) for inherited changes. |
#### com.pdf_tools.pdf.TextStampAnnotation
| [Class] `com.pdf_tools.pdf.TextStampAnnotation`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.TextStamp` |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static TextStampcreate(pdf.Document targetDocument, geometry.real.Point topleft, Double height, TextStampType type, String content)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [`StampAnnotation`](#compdf_toolspdfstampannotation) for inherited changes. |
#### com.pdf_tools.pdf.TextStampType
| [Enum.] `com.pdf_tools.pdf.TextStampType` → `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.TextStampType` |
| ---------------------------------------------------------------------------------------------------------------- |
| |
#### com.pdf_tools.pdf.UnderlineAnnotation
| [Class] `com.pdf_tools.pdf.UnderlineAnnotation`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.Underline` |
| ----------------------------------------------------------------------------------------------------------------- |
| See [TextMarkupAnnotation](#compdf_toolspdftextmarkupannotation) for inherited changes. |
### pdf.content namespace
#### com.pdf_tools.pdf.BlendMode
| [Enum.] `com.pdf_tools.pdf.BlendMode` → `com.pdf_tools.fourheights.pdftoolbox.pdf.content.BlendMode` |
| ---------------------------------------------------------------------------------------------------- |
| |
#### com.pdf_tools.fourheights.pdftoolbox.pdf.content.CalibratedGrayColorSpace
| [Class] `com.pdf_tools.fourheights.pdftoolbox.pdf.content.CalibratedGrayColorSpace` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`pdf.content.ColorSpace`](#compdf_toolspdfcolorspace). Substitutes the removed enum `ColorSpaceType`. See [Color space classes](./java-interface.mdx#color-space-classes). |
#### com.pdf_tools.fourheights.pdftoolbox.pdf.content.CalibratedRgbColorSpace
| [Class] `com.pdf_tools.fourheights.pdftoolbox.pdf.content.CalibratedRgbColorSpace` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`pdf.content.ColorSpace`](#compdf_toolspdfcolorspace). Substitutes the removed enum `ColorSpaceType`. See [Color space classes](./java-interface.mdx#color-space-classes). |
#### com.pdf_tools.fourheights.pdftoolbox.pdf.content.CalibratedCmykColorSpace
| [Class] `com.pdf_tools.fourheights.pdftoolbox.pdf.content.CalibratedCmykColorSpace` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`pdf.content.ColorSpace`](#compdf_toolspdfcolorspace). Substitutes the removed enum `ColorSpaceType`. See [Color space classes](./java-interface.mdx#color-space-classes). |
#### com.pdf_tools.pdf.ColorSpace
| [Class] `com.pdf_tools.pdf.ColorSpace`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.content.ColorSpace` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed).Renamed method `getComponents` → `getComponentCount`.Removed method `getType`.Removed method `getName`.New method `static ColorSpace createProcessColorSpace(pdf.Document targetDocument, pdf.content.ProcessColorSpaceType type)`New method `static ColorSpace copy(pdf.Document targetDocument, ColorSpace colorSpace)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [Color space classes](./java-interface.mdx#color-space-classes). |
#### com.pdf_tools.pdf.ColorSpaceType
| [Enum.] `com.pdf_tools.pdf.ColorSpaceType` |
| --------------------------------------------------------------------------- |
| Removed. See [Color space classes](./java-interface.mdx#color-space-classes). |
#### com.pdf_tools.pdf.Content
| [Class] `com.pdf_tools.pdf.Content`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.content.Content` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed). |
#### com.pdf_tools.pdf.ContentElement
| [Class] `com.pdf_tools.pdf.ContentElement`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.content.ContentElement` |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed).New method `static Content elementcopy(pdf.Document targetDocument, ContentElement contentElement)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). |
#### com.pdf_tools.pdf.ContentExtractor
| [Class] `com.pdf_tools.pdf.ContentExtractor`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.content.ContentExtractor` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed). |
#### com.pdf_tools.pdf.ContentGenerator
| [Class] `com.pdf_tools.pdf.ContentGenerator`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.content.ContentGenerator` |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed method `void paintPath(Path path, Paint fill, StrokeParams stroke, boolean intersectClipping)` → `void paintPath(Path path, Fill fill, Stroke stroke)`. See [Separate inside rule from path](./java-interface.mdx#separate-inside-rule-from-path) and [Path and text clipping operations](./java-interface.mdx#path-and-text-clipping-operations).Changed behavior of methods `paintImage` and `paintImageMask`: Value `null` for second argument of type `Rectangle` is not supported anymore.New method `void clipWithPath(pdf.content.Path path, pdf.content.InsideRule InsideRule)`. See [Separate inside rule from path](./java-interface.mdx#separate-inside-rule-from-path) and [Path and text clipping operations](./java-interface.mdx#path-and-text-clipping-operations).New method `void clipWithText(pdf.content.Text text)`. See [Path and text clipping operations](./java-interface.mdx#path-and-text-clipping-operations). |
#### com.pdf_tools.pdf.DeviceColorSpaceType
| [Enum.] `com.pdf_tools.pdf.DeviceColorSpaceType` → `com.pdf_tools.fourheights.pdftoolbox.pdf.content.ProcessColorSpaceType` |
| --------------------------------------------------------------------------------------------------------------------------- |
| Renamed enum value `R_G_B` → `RGB`.Renamed enum value `C_M_Y_K` → `CMYK`. |
#### com.pdf_tools.fourheights.pdftoolbox.pdf.content.DeviceGrayColorSpace
| [Class] `com.pdf_tools.fourheights.pdftoolbox.pdf.content.DeviceGrayColorSpace` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`pdf.content.ColorSpace`](#compdf_toolspdfcolorspace).Substitutes the removed enumColorSpaceType. See [Color space classes](./java-interface.mdx#color-space-classes). |
#### com.pdf_tools.fourheights.pdftoolbox.pdf.content.DeviceCmykColorSpace
| [Class] `com.pdf_tools.fourheights.pdftoolbox.pdf.content.DeviceCmykColorSpace` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`pdf.content.ColorSpace`](#compdf_toolspdfcolorspace).Substitutes the removed enumColorSpaceType. See [Color space classes](./java-interface.mdx#color-space-classes). |
#### com.pdf_tools.fourheights.pdftoolbox.pdf.content.DeviceRgbColorSpace
| [Class] `com.pdf_tools.fourheights.pdftoolbox.pdf.content.DeviceRgbColorSpace` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`pdf.content.ColorSpace`](#compdf_toolspdfcolorspace).Substitutes the removed enumColorSpaceType. See [Color space classes](./java-interface.mdx#color-space-classes). |
#### com.pdf_tools.pdf.FillParams
| [Struct → class] `com.pdf_tools.pdf.FillParams` → `com.pdf_tools.fourheights.pdftoolbox.pdf.content.Fill` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed constructor `FillParams(Paint paint, InsideRule fillRule)`.Renamed methods `getFillRule` and `setFillRule` → `getInsideRule1` / `setInsideRule`. See [Separate inside rule from path](./java-interface.mdx#separate-inside-rule-from-path).New constructor `Fill(Paint paint)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). |
#### com.pdf_tools.pdf.Font
| [Class] `com.pdf_tools.pdf.Font`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.content.Font` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed).Renamed method `getCharWidth` → `getCharacterWidth`.New method `static Fontcreate(pdf.Document targetDocument, sys.Stream stream, boolean embedded)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods).New method `static FontcreateFromSystem(pdf.Document targetDocument, String family, String style, boolean embedded)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods).See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). |
#### com.pdf_tools.pdf.Group
| [Class] `com.pdf_tools.pdf.Group` → `com.pdf_tools.fourheights.pdftoolbox.pdf.content.Group` |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed).New method `static Group create(pdf.Document targetDocument, geometry.real.Size size)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods).New method `static Group createFromPage(pdf.Document targetDocument, pdf.Page page, pdf.PageCopyOptions copyOptions)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). |
#### com.pdf_tools.pdf.GroupElement
| [Class] `com.pdf_tools.pdf.GroupElement`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.content.GroupElement` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static GroupElement copyWithoutContent(pdf.Document targetDocument, GroupElement groupElement)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [ContentElement](#compdf_toolspdfcontentelement) for inherited changes. |
#### com.pdf_tools.fourheights.pdftoolbox.pdf.content.IccBasedColorSpace
| [Class] `com.pdf_tools.fourheights.pdftoolbox.pdf.content.IccBasedColorSpace` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Extends [`pdf.content.ColorSpace`](#compdf_toolspdfcolorspace).Method `static pdf.content.IccBasedColorSpace create(pdf.Document targetDocument, sys.Stream profile)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). Substitutes the removed enumColorSpaceType. See [Color space classes](./java-interface.mdx#color-space-classes). |
#### com.pdf_tools.pdf.Image
| [Class] `com.pdf_tools.pdf.Image` → `com.pdf_tools.fourheights.pdftoolbox.pdf.content.Image` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed).Removed method `getWidth`. Replaced by new method `getSize`.Removed method `getHeight`. Replaced by new method `getSize`.New method `static Imagecreate(pdf.Document targetDocument, sys.Streamstream)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods).New method `geometry.integer.Size getSize()`. See [Image size and image mask size](./java-interface.mdx#image-size-and-image-mask-size). |
#### com.pdf_tools.pdf.ImageElement
| [Class] `com.pdf_tools.pdf.ImageElement`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.content.ImageElement` |
| --------------------------------------------------------------------------------------------------------- |
| See [ContentElement](#compdf_toolspdfcontentelement) for inherited changes. |
#### com.pdf_tools.pdf.ImageMask
| [Class] `com.pdf_tools.pdf.ImageMask`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.content.ImageMask` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed).Removed method `getWidth`. Replaced by new method `getSize`.Removed method `getHeight`. Replaced by new method `getSize`.New method `static ImageMask create(pdf.Document targetDocument, sys.Stream stream)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods).New method `geometry.integer.Size getSize()`. See [Image size and image mask size](./java-interface.mdx#image-size-and-image-mask-size). |
#### com.pdf_tools.pdf.ImageMaskElement
| [Class] `com.pdf_tools.pdf.ImageMaskElement` → `com.pdf_tools.fourheights.pdftoolbox.pdf.content.ImageMaskElement` |
| ------------------------------------------------------------------------------------------------------------------ |
| See [ContentElement](#compdf_toolspdfcontentelement) for inherited changes. |
#### com.pdf_tools.fourheights.pdftoolbox.pdf.content.IndexedColorSpace
| [Class] `com.pdf_tools.fourheights.pdftoolbox.pdf.content.IndexedColorSpace` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`pdf.content.ColorSpace`](#compdf_toolspdfcolorspace). Substitutes the removed enum `ColorSpaceType`. See [Color space classes](./java-interface.mdx#color-space-classes). |
#### com.pdf_tools.pdf.InsideRule
| [Enum.] `com.pdf_tools.pdf.InsideRule` → `com.pdf_tools.fourheights.pdftoolbox.pdf.content.InsideRule` |
| ------------------------------------------------------------------------------------------------------ |
| |
#### com.pdf_tools.fourheights.pdftoolbox.pdf.content.LabColorSpace
| [Class] `com.pdf_tools.fourheights.pdftoolbox.pdf.content.LabColorSpace` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`pdf.content.ColorSpace`](#compdf_toolspdfcolorspace). Substitutes the removed enum `ColorSpaceType`. See [Color space classes](./java-interface.mdx#color-space-classes). |
#### com.pdf_tools.pdf.LineCapStyle
| [Class] `com.pdf_tools.pdf.LineCapStyle` → `com.pdf_tools.fourheights.pdftoolbox.pdf.content.LineCapStyle` |
| ---------------------------------------------------------------------------------------------------------- |
| |
#### com.pdf_tools.pdf.LineJoinStyle
| [Enum.] `com.pdf_tools.pdf.LineJoinStyle` → `com.pdf_tools.fourheights.pdftoolbox.pdf.content.LineJoinStyle` |
| ------------------------------------------------------------------------------------------------------------ |
| |
#### com.pdf_tools.fourheights.pdftoolbox.pdf.content.NChannelColorSpace
| [Class] `com.pdf_tools.fourheights.pdftoolbox.pdf.content.NChannelColorSpace` |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`pdf.content.ColorSpace`](#compdf_toolspdfcolorspace).Substitutes the removed enum `ColorSpaceType`. See [Color space classes](./java-interface.mdx#color-space-classes). |
#### com.pdf_tools.pdf.Paint
| [Class] `com.pdf_tools.pdf.Paint`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.content.Paint` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed).New method `static Paint create(pdf.Document targetDocument, pdf.content.ColorSpace colorSpace, double[] color, pdf.content.Transparency transparency)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods) and [Unified paint creation](./java-interface.mdx#unified-paint-creation). |
#### com.pdf_tools.pdf.Path
| [Class] `com.pdf_tools.pdf.Path`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.content.Path` |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed).Changed constructor `Path(FillRule rule)` → `Path()`. See [Separate insiderule from path](./java-interface.mdx#separate-inside-rule-from-path). |
#### com.pdf_tools.pdf.PathElement
| [Class] `com.pdf_tools.pdf.PathElement`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.content.PathElement` |
| ------------------------------------------------------------------------------------------------------- |
| See [ContentElement](#compdf_toolspdfcontentelement) for inherited changes. |
#### com.pdf_tools.pdf.PathGenerator
| [Class] `com.pdf_tools.pdf.PathGenerator`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.content.PathGenerator` |
| ----------------------------------------------------------------------------------------------------------- |
| |
#### com.pdf_tools.fourheights.pdftoolbox.pdf.content.SeparationColorSpace
| [Class] `com.pdf_tools.fourheights.pdftoolbox.pdf.content.SeparationColorSpace` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`pdf.content.ColorSpace`](#compdf_toolspdfcolorspace). Substitutes the removed enum `ColorSpaceType`. See [Color space classes](./java-interface.mdx#color-space-classes). |
#### com.pdf_tools.pdf.ShadingElement
| [Class] `com.pdf_tools.pdf.ShadingElement`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.content.ShadingElement` |
| ------------------------------------------------------------------------------------------------------------- |
| See [ContentElement](#compdf_toolspdfcontentelement) for inherited changes. |
#### com.pdf_tools.pdf.StrokeParams
| [Struct → class] `com.pdf_tools.pdf.StrokeParams` → `com.pdf_tools.fourheights.pdftoolbox.pdf.content.Stroke` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed constructor `StrokeParams(Paint paint, double lineWidth, LineCapStyle lineCapStyle, LineJoinStyle lineJoinStyle, double[] dashArray, double dashPhase, double miterLimit)`.New constructor `Stroke(Paint paint, double lineWidth)`.See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). |
#### com.pdf_tools.pdf.Text
| [Class] `com.pdf_tools.pdf.Text`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.content.Text` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed).New method `static Textcreate(pdf.Document targetDocument)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). |
#### com.pdf_tools.pdf.TextElement
| [Class] `com.pdf_tools.pdf.TextElement`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.content.TextElement` |
| ------------------------------------------------------------------------------------------------------- |
| See [ContentElement](#compdf_toolspdfcontentelement) for inherited changes. |
| [Class] `com.pdf_tools.pdf.TextFragment`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.content.TextFragment` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed).Renamed method `getUnicodeString` → `getText`. |
#### com.pdf_tools.pdf.TextGenerator
| [Class] `com.pdf_tools.pdf.TextGenerator`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.content.TextGenerator` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed method `setRendering`. Replaced by methods `setFill` and `setStroke`. See [Text generator](./java-interface.mdx#text-generator).Renamed method `setCharSpacing` → `setCharacterSpacing`. See [Renaming](./java-interface.mdx#renaming).New methods `Paint getFill()`and `void setFill(PaintFill)`.New methods `Stroke getStroke()` and `void setStroke(Stroke Stroke)`. |
#### com.pdf_tools.pdf.TransparencyParams
| [Struct → Class] `com.pdf_tools.pdf.TransparencyParams` → `com.pdf_tools.fourheights.pdftoolbox.pdf.content.Transparency` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Removed constructor `TransparencyParams(BlendMode blendMode, double constAlpha)`.Renamed methods `getConstAlpha` and `setConstAlpha`→ `getAlpha` / `setAlpha`.New constructor `Transparency(double alpha)`. |
#### com.pdf_tools.pdf.UngroupingSet
| [Enum.] `com.pdf_tools.pdf.UngroupingSet` → `com.pdf_tools.fourheights.pdftoolbox.pdf.content.UngroupingSelection` |
| ------------------------------------------------------------------------------------------------------------------ |
| |
### pdf.forms namespace
#### com.pdf_tools.pdf.CheckBoxField
| [Class] `com.pdf_tools.pdf.CheckBoxField`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.CheckBox` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static CheckBoxcreate(pdf.Document targetDocument)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [FormField](#compdf_toolspdfformfield) for inherited changes. |
#### com.pdf_tools.pdf.ChoiceField
| [Class] `com.pdf_tools.pdf.ChoiceField`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.ChoiceField` |
| ----------------------------------------------------------------------------------------------------- |
| See [FormField](#compdf_toolspdfformfield) for inherited changes. |
#### com.pdf_tools.pdf.ChoiceItem
| [Class] `com.pdf_tools.pdf.ChoiceItem`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.ChoiceItem` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed). |
#### com.pdf_tools.pdf.ChoiceItemList
| [Class] `com.pdf_tools.pdf.ChoiceItemList`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.ChoiceItemList` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed). |
#### com.pdf_tools.pdf.ComboBoxField
| [Class] `com.pdf_tools.pdf.ComboBoxField`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.ComboBox` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static ComboBoxcreate(pdf.Document targetDocument)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [ChoiceField](#compdf_toolspdfchoicefield) for inherited changes. |
#### com.pdf_tools.pdf.CombTextField
| [Class] `com.pdf_tools.pdf.CombTextField`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.CombTextField` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static CombTextFieldcreate(pdf.Document targetDocument, int maxLength)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods).New methods `int getMaxLength()` and `void setMaxLength(int MaxLength)`. See [MaxLength in text fields](./java-interface.mdx#maxlength-in-text-fields. See [TextField](#compdf_toolspdftextfield) for inherited changes. |
#### com.pdf_tools.pdf.FormField
| [Class] `com.pdf_tools.pdf.FormField`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.Field` |
| --------------------------------------------------------------------------------------------- |
| See [FormFieldNode](#compdf_toolspdfformfieldnode) for inherited changes. |
#### com.pdf_tools.fourheights.pdftoolbox.pdf.forms.FormFieldCopyStrategy
| [Enum.] `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.FormFieldCopyStrategy` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Values:`COPY``FLATTEN``REMOVE``COPY_AND_UPDATE_WIDGETS`Substitutes the removedCopyOption. See [Copy options](./java-interface.mdx#copy-options). |
#### com.pdf_tools.pdf.FormFieldNode
| [Class] `com.pdf_tools.pdf.FormFieldNode`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.FieldNode` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed).New method `static FieldNode copy(pdf.Document targetDocument, FieldNode fieldNode)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). |
#### com.pdf_tools.pdf.FormFieldNodeMap
| [Class] `com.pdf_tools.pdf.FormFieldNodeMap`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.FieldNodeMap` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed). |
#### com.pdf_tools.pdf.GeneralTextField
| [Class] `com.pdf_tools.pdf.GeneralTextField`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.GeneralTextField` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static GeneralTextField create(pdf.Document targetDocument)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods).New methods `Integer getMaxLength()` and `void setMaxLength(Integer MaxLength)`. See [MaxLength in text fields](./java-interface.mdx#maxlength-in-text-fields). See [TextField](#compdf_toolspdftextfield) for inherited changes. |
#### com.pdf_tools.pdf.ListBoxField
| [Class] `com.pdf_tools.pdf.ListBoxField`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.ListBox` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static ListBox create(pdf.Document targetDocument)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [ChoiceField](#compdf_toolspdfchoicefield) for inherited changes. |
#### com.pdf_tools.pdf.PushButtonField
| [Class] `com.pdf_tools.pdf.PushButtonField`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.PushButton` |
| -------------------------------------------------------------------------------------------------------- |
| |
#### com.pdf_tools.pdf.RadioButton
| [Class] `com.pdf_tools.pdf.RadioButton`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.RadioButton` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed). |
#### com.pdf_tools.pdf.RadioButtonField
| [Class] `com.pdf_tools.pdf.RadioButtonField`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.RadioButtonGroup` |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed methods `getCanToggleOff` and `setCanToggleOff`.New method `static RadioButtonGroup create(pdf.Document targetDocument)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [FormField](#compdf_toolspdfformfield) for inherited changes. |
#### com.pdf_tools.pdf.RadioButtonList
| [Class] `com.pdf_tools.pdf.RadioButtonList`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.RadioButtonList` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed). |
#### com.pdf_tools.pdf.SignatureField
| [Class] `com.pdf_tools.pdf.SignatureField`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.SignatureField` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed).Changed type of method `getDate` from `java.util.Calendar` to `java.time.OffsetDateTime`. See [OffsetDateTime](./java-interface.mdx#offsetdatetime). |
#### com.pdf_tools.pdf.SignatureFieldList
| [Class] `com.pdf_tools.pdf.SignatureFieldList`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.SignatureFieldList` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed). |
#### com.pdf_tools.pdf.SubForm
| [Class] `com.pdf_tools.pdf.SubForm`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.SubForm` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static SubForm create(pdf.Document targetDocument)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [FormFieldNode](#compdf_toolspdfformfieldnode) for inherited changes. |
#### com.pdf_tools.pdf.TextField
| [Class] `com.pdf_tools.pdf.TextField`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.TextField` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed methods `getMaxLength` and `setMaxLength`. See[MaxLength in text fields](./java-interface.mdx#maxlength-in-text-fields). See [FormFieldNode](#compdf_toolspdfformfieldnode) for inherited changes. |
#### com.pdf_tools.pdf.Widget
| [Class] `com.pdf_tools.pdf.Widget`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.Widget` |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed inheritance from class `Annotation`. See [Annotations](./java-interface.mdx#annotations).Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed).Duplicated method `geometry.real.Rectangle getBoundingBox()` from former base class `Annotation`.Duplicated method `boolean getHidden()`from former base class `Annotation`.Duplicated method `boolean getNoPrint()` from former base class `Annotation`. |
#### com.pdf_tools.pdf.WidgetList
| [Class] `com.pdf_tools.pdf.WidgetList`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.WidgetList` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed). |
### pdf.navigation namespace
#### com.pdf_tools.pdf.Destination
| [Class] `com.pdf_tools.pdf.Destination`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.Destination` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed). |
#### com.pdf_tools.pdf.DirectDestination
| [Class] `com.pdf_tools.pdf.DirectDestination`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.DirectDestination` |
| ---------------------------------------------------------------------------------------------------------------------- |
| See [Destination](#compdf_toolspdfdestination) for inherited changes. |
#### com.pdf_tools.pdf.EmbeddedPdfLink
| [Class] `com.pdf_tools.pdf.EmbeddedPdfLink`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.EmbeddedPdfLink` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed constructor. See [Constructors](./java-interface.mdx#constructors).New method `static EmbeddedPdfLink create(pdf.Document targetDocument, geometry.real.Rectangle boundingBox, pdf.FileReference fileReference)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods).SeeLinkfor inherited changes. |
#### com.pdf_tools.pdf.FitHeightDestination
| [Class] `com.pdf_tools.pdf.FitHeightDestination`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.FitHeightDestination` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed constructor. See [Constructors](./java-interface.mdx#constructors).New method `static FitHeightDestination create(pdf.Document targetDocument, pdf.Page page, boolean fitActualContent)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [DirectDestination](#compdf_toolspdfdirectdestination) for inherited changes. |
#### com.pdf_tools.pdf.FitPageDestination
| [Class] `com.pdf_tools.pdf.FitPageDestination`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.FitPageDestination` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed constructor. See [Constructors](./java-interface.mdx#constructors).New method `static FitPageDestination create(pdf.Document targetDocument, pdf.Page page, boolean fitActualContent)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods).See [DirectDestination](#compdf_toolspdfdirectdestination) for inherited changes. |
#### com.pdf_tools.pdf.FitRectangleDestination
| [Class] `com.pdf_tools.pdf.FitRectangleDestination`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.FitRectangleDestination` |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed constructor. See [Constructors](./java-interface.mdx#constructors).New method `static FitRectangleDestination create(pdf.Document targetDocument, pdf.Page page, geometry.real.Rectangle rectangle)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [DirectDestination](#compdf_toolspdfdirectdestination) for inherited changes. |
#### com.pdf_tools.pdf.FitWidthDestination
| [Class] `com.pdf_tools.pdf.FitWidthDestination`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.FitWidthDestination` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Removed constructor. See [Constructors](./java-interface.mdx#constructors).New method `static FitWidthDestination create(pdf.Document targetDocument, pdf.Page page, boolean fitActualContent)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [DirectDestination](#compdf_toolspdfdirectdestination) for inherited changes. |
#### com.pdf_tools.pdf.InternalLink
| [Class] `com.pdf_tools.pdf.InternalLink`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.InternalLink` |
| ------------------------------------------------------------------------------------------------------------ |
| See [Link](#compdf_toolspdflink) for inherited changes. |
#### com.pdf_tools.pdf.Link
| [Class] `com.pdf_tools.pdf.Link`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.Link` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed inheritance from class `Annotation`. See [Annotations](./java-interface.mdx#annotations).Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed).New method `static Link copy(pdf.Document targetDocument, Link link)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods).Duplicated method `geometry.real.Rectangle getBoundingBox()` from former base class `Annotation`.Duplicated method `boolean getHidden()` from former base class `Annotation`.Duplicated method `boolean getNoPrint()` from former base class `Annotation`. |
#### com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.LinkList
| [Class] `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.LinkList` |
| ---------------------------------------------------------------------- |
| A list that contains [Link](#compdf_toolspdflink) objects. |
#### com.pdf_tools.pdf.LocationZoomDestination
| [Class] `com.pdf_tools.pdf.LocationZoomDestination`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.LocationZoomDestination` |
| ---------------------------------------------------------------------------------------------------------------------------------- |
|
Removed constructor. See [Constructors](./java-interface.mdx#constructors).
New method `static ZoomDestination create(pdf.Document targetDocument, pdf.Page page, Double left, Double top,Double zoom)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [DirectDestination](#compdf_toolspdfdirectdestination) for inherited changes. |
#### com.pdf_tools.pdf.NamedDestination
| [Class] `com.pdf_tools.pdf.NamedDestination`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.NamedDestination` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static NamedDestination create(pdf.Document targetDocument, String name, DirectDestination target)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [Destination](#compdf_toolspdfdestination) for inherited changes. |
#### com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.NamedDestinationCopyStrategy
| [Enum] `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.NamedDestinationCopyStrategy` |
| --------------------------------------------------------------------------------------------------------------------------------------------- |
| Values:`COPY` `RESOLVE` Substitutes the removed `CopyOption`. See [Copy options](./java-interface.mdx#copy-options). |
#### com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.OutlineCopyOptions
| [Class] `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.OutlineCopyOptions` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| constructor `OutlineCopyOptions()`Methods `pdf.navigation.NamedDestinationCopyStrategy getNamedDestinations()` and `void setNamedDestinations(pdf.navigation.NamedDestinationCopyStrategy NamedDestinations)`Default: `NamedDestinationCopyStrategy.COPY`Methods `boolean getCopyLogicalStructure()` and `void setCopyLogicalStructure(boolean CopyLogicalStructure)`Default: `true` Substitutes the removed `CopyOption`. See [Copy options](./java-interface.mdx#copy-options). |
#### com.pdf_tools.pdf.OutlineItem
| [Class] `com.pdf_tools.pdf.OutlineItem`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.OutlineItem` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed).New method `static OutlineItem create(pdf.Document targetDocument, String title, Destination Destination)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods).New method `static OutlineItem copy(pdf.Document targetDocument, OutlineItem outlineItem, OutlineCopyOptions options)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [Copy options](./java-interface.mdx#copy-options). |
#### com.pdf_tools.pdf.OutlineItemLists
| [Class] `com.pdf_tools.pdf.OutlineItemList`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.OutlineItemList` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed). |
#### com.pdf_tools.pdf.PageDisplay
| [Struct] `com.pdf_tools.pdf.PageDisplay` → `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.PageDisplay` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New base class `com.pdf_tools.fourheights.pdftoolbox.internal.NativeBase`. See [Structs extend NativeBase](./java-interface.mdx#structs-extend-nativebase).Changed default value of `fieldcontinuous` from `true` to `false`. |
#### com.pdf_tools.pdf.PageLayout
| [Enum.] `com.pdf_tools.pdf.PageLayout` → `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.PageLayout` |
| --------------------------------------------------------------------------------------------------------- |
| |
#### com.pdf_tools.pdf.ViewerNavigationPane
| [Enum.] `com.pdf_tools.pdf.ViewerNavigationPane` → `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.ViewerNavigationPane` |
| ----------------------------------------------------------------------------------------------------------------------------- |
| |
#### com.pdf_tools.pdf.ViewerSettings
| [Class] `com.pdf_tools.pdf.ViewerSettings`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.ViewerSettings` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static ViewerSettings copy(pdf.Document targetDocument, ViewerSettings viewerSettings)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). |
#### com.pdf_tools.pdf.WebLink
| [Class] `com.pdf_tools.pdf.WebLink`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.WebLink` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed constructor. See [Constructors](./java-interface.mdx#constructors).New method `static WebLink create(pdf.Document targetDocument, geometry.real.Rectangle boundingBox, String uri)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [Link](#compdf_toolspdflink) for inherited changes. |
## sys namespace
#### com.pdf_tools.FileStream
| [Class] `com.pdf_tools.FileStream`→ `com.pdf_tools.fourheights.pdftoolbox.sys.FileStream` |
| ----------------------------------------------------------------------------------------- |
| |
#### com.pdf_tools.MemoryStream
| [Class] `com.pdf_tools.MemoryStream`→ `com.pdf_tools.fourheights.pdftoolbox.sys.MemoryStream` |
| --------------------------------------------------------------------------------------------- |
| |
#### com.pdf_tools.Stream
| [Class] `com.pdf_tools.Stream`→ `com.pdf_tools.fourheights.pdftoolbox.sys.Stream` |
| --------------------------------------------------------------------------------- |
| |
---
## Use the source code migration script for the PDF Toolbox SDK
You can use the PDF Toolbox SDK Python script (`3hto4h.py`) to automate the major part of source code migration from the 3-Heights® PDF Toolbox API to the PDF Toolbox SDK.
:::note Before you start
Python 3.4 or later is required.
:::
1. Back up your source code, if necessary.
2. Execute the script, where `‹dir›` is the root directory of your source tree:
```
python 3hto4h.py ‹dir›
```
3. The script iterates through files contained in the given directory and all its subdirectories (recursively), and processes the following file types:
- \*.c, \*.cpp, \*.cxx
- \*.h, \*.hpp, \*.hxx
- \*.java
- \*.cs
Each matching file is processed in-place.
The processing consists solely of regular expression substitutions, which fall into two categories:
- Source code replacement
- Marking of code that needs attention by appending a trailing comment:
```
... //TODO 3H->4H: ‹message›
```
4. You can switch off the code marking by executing the script with the `-m` option:
```
python 3hto4h.py -m ‹dir›
```
:::note
The substitutions done in this script **do not completely migrate all source code**. Compiler errors indicate code that needs manual migration.
In some situations, the script can falsely replace code that has no connection to the 3-Heights® PDF Toolbox API. Such changes must be undone.
The `//TODO 3H->4H` markers help to locate code that could not be migrated completely or behavioral changes that need manual implementation.
:::
---
## About the PDF Toolbox SDK
The PDF Toolbox SDK is a native library with interfaces for .NET, Java, and C for creating, extracting, assembling, and modifying PDF documents.
---
## Key features
### Document generation
The PDF Toolbox SDK lets you create PDF files, defining structure at document level and content at page level.
#### Create PDF document definition
You can create a new document from scratch, determining the pages in the document tree, adding form fields, and adding outline items.
- Create pages
- Create form fields:
- General text fields and comb text fields
- Check boxes
- Radio button groups
- List boxes
- Combo boxes
- Create new outline items and insert them at any position in the tree
- Destinations: Named and direct destinations in the same document
- Configure viewer settings
#### Create content at page level
- Create new PDF content from scratch
- Apply content to existing pages
**Determine colors**
- Device colors: RGB, CMYK, and grayscale
- ICC color profiles
- Transparency: alpha and blend mode
**Add trace paths**
- Single and multi-segment lines
- Rectangle, circle, Bezier curves, ellipse, arc, pie
- Filling, stroking, clipping, and combinations thereof
- Line width, cap, join, dash array, dash phase, and miter limit
- Inside rule: nonzero winding rule, even/odd rule
**Add text**
- Font size, character spacing, word spacing
- Horizontal scaling, leading, rise
- Enables simple text layouting
- Standard PDF fonts, installed fonts
- Font metrics: italic angle, ascent, descent, cap height, character width
- Unicode characters
- Text stroke: line width, line join, and dashes
- Fill and stroke text, invisible text
- Use text as clipping path
**Add images**
- Bi-level: CCITT G3, G3 2D and G4, Flate, LZW, Packbits, uncompressed
- 4 bit and 8 bit grayscale: Flate, LZW, Packbits, JPEG and JPEG-6 (8 bit only), uncompressed
- RGB: Flate, JPEG and JPEG-6, LZW, Packbits, uncompressed
**Add transformations**
- Translation
- Scaling
- Skewing (horizontal, vertical)
- Rotation
#### Create annotations and links
You can add multiple annotation types such as text, stamps, drawings, and text revision marks to the PDF pages. You can add internal links such as section references and external links to specific web pages or embedded files.
- Document-internal links
- Web links
- Links to embedded PDFs
- File attachment annotations
- Free text annotation
- Sticky note annotation
- Text stamp annotation
- Custom stamp annotation
- Circle annotation
- Square annotation
- Line annotation
- Poly line annotation
- Polygon annotation
- Ink annotation (pen drawing)
- Highlight annotation
- Underline and squiggly underline annotation
- Strike-through annotation
### Document modification
The PDF Toolbox SDK lets you edit PDF files, deleting objects, adding markup annotations, deleting or changing field values.
#### Edit page content
- Selectively delete content elements (without tagging and layers)
- Transform content elements geographically (without tagging and layers)
#### Edit annotations
- Web link annotation target URIs
- Markup annotation location, creation and modification date, subject, author, content
#### Edit form fields
- Delete fields and modify field values for:
- General text fields and comb text fields
- Check boxes
- Radio button groups
- List boxes
- Combo boxes
### Document extraction
The PDF Toolkit SDK lets you extract data and text from PDF files.
#### Extract data from document and page level
You can extract specific data from PDF documents, either at document or page level. Information you can extract includes metadata, page content, encryption settings, and information about embedded files.
- Document information entries: title, author, subject, keywords, creator, producer, creation date, modification date
- Document XMP metadata
- Document encryption settings
- Embedded files
- Page bounding boxes: media box, crop box, bleed box, trim box, art box
- Page XMP metadata
- Outline item tree: Tree structure, item title, expanded/collapsed
- Destinations: Named and direct destinations in the same document
- Viewer settings
#### Extract content
- Page and group content elements, including:
- Bounding box
- Affine transformation
As either of the following:
- Group element
- Image element
- Width and height in pixel
- Bits per component
- Color space
- Image mask element
- Width and height in pixel
- Paint for filling the mask
- Path element
- Alignment box
- Subpaths and subpath segments
- Fill parameters including paint and fill rule
- Stroke parameters including line paint and line style
- Shading element
- Text element
- Text fragments
- Bounding box
- Affine transformation
- Unicode string
- Fill parameters, including paint and fill rule
- Stroke parameters, including line paint and line style
- Font size, character spacing, word spacing, horizontal scaling, and text rise
#### Extract annotations
- Annotations: location
- Markup annotation: type, location, creation/modification date, subject, author, content
- Custom stamp annotations: appearance
- Text markup annotations: markup area
- Link annotations: location, target destination or URI, active link area
- Signature fields: name, location, reason, contact info, date, visibility
#### Extract AcroForm form fields
- Form field identifiers, export names, and user names, including form field hierarchy
- Form field export and display content of:
- Push buttons
- Check boxes
- Radio button groups
- General text fields and comb text fields
- List boxes
- Combo boxess
### Document assembly
The PDF Toolbox SDK lets you assemble PDF files from existing PDF files.
#### Assemble PDF files
- Copy pages from existing PDFs
- Copy annotations, form fields, links, logical structure, destinations, outlines, and layers
- Flatten annotations, form fields, and signatures
- Optimize resources
- Crop and rotate pages
- Compose content: overlays, underlays, stamps, transformations
- Add encryption: user password, owner password, permissions
- Copy and modify document metadata
- Copy and modify page metadata
- Add embedded files and associated files
- Get and set OpenAction destination
- Merge a PDF and an FDF
- Separate markup annotations into an FDF
## Document model
The document model of the {props.name} consists of two different types of objects:
- **Structure objects**: define the structure of the document. These objects include `Document`, `Page`, and `Content`.
- **Graphics resources**: used to draw content with a [ContentGenerator](#generator-objects). Examples are `Image`, `Font`, and `ColorSpace`.
All objects in the document model are bound to a specific document. They can only be used in the context of the document for which they were created. The objects of the document model are all stateless. Where a stateful interface is required, it is provided by an external generator or extractor, which is not considered part of the document model.
The PDF Toolbox SDK does not allow in-place modification of documents. Instead, the content is copied into a new document, while performing the necessary changes.
To copy objects from a source document into a target document, you call the object’s static `Copy` method with the target document as first argument. This means you can process very large files without consuming too much memory. The content of the input document is only read on demand and any modifications can be directly stored in the output file.
To provide a uniform interface, operations are divided into two steps:
1. [Create (or copy) the object](#create-the-object)
2. [Use the object](#use-the-object)
This separation means there are multiple variants for both steps, without having a “combinatorical explosion” of methods.
#### Create the object
The object is created in the target document or copied from the source document to the target document.
After creation, the object is associated with the document, but not yet used. This means that copying or creating an object may change the size of the target file. However, logically, the PDF is still unchanged.
For example, these methods can be used to create an object:
- `Page.Create`
- `Font.Create`
- `Page.Copy`
- `PageList.Copy`
- `ColorSpace.Copy`
- `Metadata.Copy`
- `ContentElement.Copy`
#### Use the object
The associated object can then be used in the target document.
This second step is often more lightweight than the first step, since all the necessary copying of objects is already done.
For example, these methods of the `ContentGenerator` generator object are used:
- `PaintImage`
- `PaintGroup`
- `AppendContentElement`
or the `PageList.Add` method.
### Generator objects
Some objects in a PDF consist of a list or stream of operations that operate on an internal state:
- Content streams
- Text objects
- Path objects
Since all data objects in the PDF Toolbox SDK are stateless, a (simplified) stateful interface is provided by the generator interfaces:
- Content objects can be modified with a `ContentGenerator`.
- Path objects can be modified with a `PathGenerator`.
- Text objects can be modified with a `TextGenerator`.
Generator objects must always be closed explicitly before the generated object can be used.
### Garbage collection and closing objects
Every interface object is considered to be a resource that needs to be closed after use. Most objects are closed automatically, at the latest when the owning document is closed (in C# and Java), possibly earlier by the garbage collector.
In addition to `Document` objects, the [generator objects](#generator-objects) `ContentGenerator`, `PathGenerator`, and `TextGenerator` must be closed. Otherwise, the generated objects are incomplete.
## Thread safety
The PDF Toolbox SDK is generally thread-safe. However, a **document may only be accessed in one thread concurrently, including all subobjects.**
Almost all objects are directly or indirectly associated with a document.
:::note
Methods that copy from a source to a target document have to access both documents.
The thread safety rules **apply both to the target document and the source document**. This means that copying from the same source document concurrently is not allowed.
:::
### Garbage collection and finalizer
Object finalization is thread-safe.
:::caution
**The finalizer of the `Document` is not thread-safe regarding access to its subobjects.**
:::
Subobjects do not retain their associated document object. If all references to an open document go out of scope, the document finalizer is eventually run and the document is closed.
:::danger
Explicitly accessing (or even closing) any subobject while the document finalizer is running is not safe!
:::
## PDF graphics model
### Coordinate system
PDF coordinates are measured from bottom to top, unlike many other coordinate systems used in IT.
{/*Include converted graphics */}
For the sake of simplicity, all coordinates used in the PDF Toolbox SDK are normalized such that the point (0,0) denotes the lower left corner of the visible page (crop box).
The internal `Rotate` attribute of a PDF page is not exposed at the API. Instead, all coordinates are assumed to refer to the already rotated page.
### Affine transformations
Affine transformations can be used to rotate, move, scale, or otherwise, skew any page content.
{/*Include converted graphics */}
Transformations always affect the coordinate system as a whole. All following graphics operations are executed in
the transformed coordinate system, including additional transformations.
{/*Include converted graphics */}
This means that the ordering of how transformations are applied is important.
{/*Include converted graphics */}
---
## Release notes for the PDF Toolbox SDK
## Version 4.4.11
27 June 2025
### Added
- You can now call the [GetResolution](https://api-reference.pdf-tools.com/toolsdk/4.4/dotnet/html/M_PdfTools_FourHeights_PdfToolbox_Pdf_Content_ImageMask_GetResolution.htm) method of the [ImageMask](https://api-reference.pdf-tools.com/toolsdk/4.4/dotnet/html/T_PdfTools_FourHeights_PdfToolbox_Pdf_Content_ImageMask.htm) class.
## Version 4.4.10
19 June 2025
### Added
- You can now call the [GetResolution](https://api-reference.pdf-tools.com/toolsdk/4.4/dotnet/html/M_PdfTools_FourHeights_PdfToolbox_Pdf_Content_Image_GetResolution.htm) method of the [Image](https://api-reference.pdf-tools.com/toolsdk/4.4/dotnet/html/T_PdfTools_FourHeights_PdfToolbox_Pdf_Content_Image.htm) class.
## Version 4.4.9
13 March 2025
### Fixed
- Prior to this release, radio buttons were improperly copied to the output document.
- Fixed a regression that caused decryption to fail for encrypted PDFs using a specific encryption algorithm.
- Improved handling of faulty PostScript string syntax to ensure correct parsing of ToUnicode maps.
## Version 4.4
17 October 2023
### Added
- You can now call the [Extract](https://api-reference.pdf-tools.com/toolsdk/4.4/dotnet/html/M_PdfTools_FourHeights_PdfToolbox_Pdf_Content_Image_Extract.htm) method of the [Image](https://api-reference.pdf-tools.com/toolsdk/4.4/dotnet/html/T_PdfTools_FourHeights_PdfToolbox_Pdf_Content_Image.htm) and [ImageMask](https://api-reference.pdf-tools.com/toolsdk/4.4/dotnet/html/T_PdfTools_FourHeights_PdfToolbox_Pdf_Content_ImageMask.htm) classes to extract an image in [various output formats](../use/extract/#extract-images).
- Retrieve stored image samples by accessing the [Samples](https://api-reference.pdf-tools.com/toolsdk/4.4/dotnet/html/P_PdfTools_FourHeights_PdfToolbox_Pdf_Content_Image_Samples.htm) property of the [Image](https://api-reference.pdf-tools.com/toolsdk/4.4/dotnet/html/T_PdfTools_FourHeights_PdfToolbox_Pdf_Content_Image.htm) class.
- As of this update, you can use [memory streams](https://api-reference.pdf-tools.com/toolsdk/4.4/cdoc/_pdf_toolbox___ptx_sys_8h.html#a585bc83936fa48f1b6364327c0da4f01) with the C API.
- Check if a PDF document is linearized by accessing the [IsLinearized](https://api-reference.pdf-tools.com/toolsdk/4.4/dotnet/html/P_PdfTools_FourHeights_PdfToolbox_Pdf_Document_IsLinearized.htm) property of the [Document](https://api-reference.pdf-tools.com/toolsdk/4.4/dotnet/html/T_PdfTools_FourHeights_PdfToolbox_Pdf_Document.htm) class.
- Retrieve page labels as alternate page numbers by accessing the [PageLabel](https://api-reference.pdf-tools.com/toolsdk/4.4/dotnet/html/P_PdfTools_FourHeights_PdfToolbox_Pdf_Page_PageLabel.htm) property of the [Page](https://api-reference.pdf-tools.com/toolsdk/4.4/dotnet/html/T_PdfTools_FourHeights_PdfToolbox_Pdf_Page.htm) class.
### Fixed
- Fixed an issue that could cause the PDF Toolbox SDK to terminate unexpectedly when using the [ContentExtractor](https://api-reference.pdf-tools.com/toolsdk/4.4/dotnet/html/T_PdfTools_FourHeights_PdfToolbox_Pdf_Content_ContentExtractor.htm) class to iterate through the content of a page.
## Version 4.3
20 July 2023
### Updated C API ZIP archive layout
- The C API ZIP archive directory layout has been updated (see [Install](install/README.mdx)).
### Updated Java API ZIP archive layout
- The Java API ZIP archive directory layout has been updated (see [Install](install/README.mdx)).
### Linux
- The minimum required glibc version was upgraded from 2.27 to 2.34.
## Version 4.2
15 May 2023
### Pdf.Annotations.TextStamp
- Deprecated static method `createRaw`.
- New static method `create`.
### Pdf.Content.TextFragment (.NET and Java)
- New method `remove`.
### Pdf.Annotations.FreeText
- Changed static method `Create`: Extended with optional `Stroke`.
### Pdf.Annotations.FreeText
- New property `FontSize`.
### Pdf (.NET and Java)
- Changed the following classes to be abstract:
- `Pdf.Content.ColorSpace`
- `Pdf.Content.ContentElement`
- `Pdf.Forms.ChoiceField`
- `Pdf.Forms.Field`
- `Pdf.Forms.FieldNode`
- `Pdf.Forms.TextField`
- `Pdf.Navigation.Destination`
- `Pdf.Navigation.DirectDestination`
- `Pdf.Navigation.Link`
## Version 4.1
28 March 2023
### Pdf.Metadata
- New method `setCreationDate`.
### Pdf.Annotations.Annotation
- New property (get) `Name`.
## Version 4.0
23 January 2023
### Sdk
- Changed behavior of static property `ProducerFullName`. The producer full name is returned instead of the product name.
### Pdf.Content
- New enumeration `FontWeight`.
**Pdf.Content.Font**
- New property (get) `Weight`.
**Pdf.Content.Glyph**
- New property (get) `Width`.
### Pdf.Document
- Changed behavior of static methods `Create` and `CreateWithFdf`. A `ConformanceException` is generated if the conformance level is lower than 1.7 and Unicode passwords are specified.
### Pdf.Permission
- New enumeration items `All` and `None`.
### Sys.MemoryStream (Java only)
- New constructor from an `InputStream`.
- New method `read`.
- New method `readAllBytes`.
- New method `toByteArray`.
- New method `transferFrom`.
- New method `transferTo`.
- Removed all `MemoryStream` constructors accepting "blockSize" as an argument.
### Sys.FileStream (Java only)
- New enumeration `FileStream.Mode`.
- Changed type of the "mode" argument in `FileStream` constructors from `String` to `FileStream.Mode`.
---
## Version 3.10
28 September 2022
### Pdf.Content
- > New class `Subpath`.
- New struct `PathSegment`.
- New enumeration `PathSegmentType`.
### Pdf.Content.Path
- New extension of interface: Now extracted `Path`s are an iterable for contained `Subpath`s.
### Pdf.Document
- New static method `CreateWithFdf` to store markup annotations in a separate FDF document.
## Version 3.8
16 June 2022
### Pdf.Content.ContentGenerator
- Removed errors `IO` and `Corrupt` from `ContentGenerator` constructor.
## Version 3.6
21 April 2022
### Pdf.Annotations.AnnotationList (.NET only)
- Changed methods `Clear`, `Remove` and `RemoveAt`: Since these methods are not supported they are now implemented explicitly.
### Pdf.Annotations.MarkupInfoList (.NET only)
- Changed methods `Add`, `Clear`, `Remove` and `RemoveAt`: Since these methods are not supported they are now implemented explicitly.
### Pdf.Content.Text (.NET only)
- Changed method `Add`: Since this method is not supported it is now implemented explicitly.
### Pdf.Content.TextFragment (.NET only)
- Changed methods `Add`, `Clear`, `Remove` and `RemoveAt`: Since these methods are not supported they are now implemented explicitly.
### Pdf.Forms.FieldNodeMap (.NET only)
- Changed methods `Clear` and `Remove`: Since these methods are not supported they are now implemented explicitly.
### Pdf.Forms.RadioButtonList (.NET only)
- Changed methods `Add`, `Clear`, `Remove` and `RemoveAt`: Since these methods are not supported they are now implemented explicitly.
### Pdf.Forms.SignatureFieldList (.NET only)
- Changed methods `Add`, `Clear`, `Remove` and `RemoveAt`: Since these methods are not supported they are now implemented explicitly.
### Pdf.Forms.WidgetList (.NET only)
- Changed methods `Clear`, `Remove` and `RemoveAt`: Since these methods are not supported they are now implemented explicitly.
### Pdf.Navigation.LinkList (.NET only)
- Changed methods `Clear`, `Remove` and `RemoveAt`: Since these methods are not supported they are now implemented explicitly.
### Pdf.FileReferenceList (.NET only)
- Changed methods `Clear`, `Remove` and `RemoveAt`: Since these methods are not supported they are now implemented explicitly.
### Pdf.PageList (.NET only)
- Changed methods `Clear`, `Remove` and `RemoveAt`: Since these methods are not supported they are now implemented explicitly.
## Version 3.4
23 February 2022
### Pdf.Content
- New enumeration `WritingMode`.
- New class `Glyph`.
### Pdf.Content.TextFragment
- New extension of interface: Now this is an iterable for contained `Glyph`s.
- New property (get) `Font`
## Version 3.3
26 January 2022
### Pdf.Navigation.WebLink
- Changed error behavior of property setter for `Uri`: An `IllegalArgument` error is generated if the given value is empty.
- Changed error behavior of methods `Create` and `CreateFromQuadrilaterals`: An `IllegalArgument` error is generated if the given `uri` argument is empty.
### Pdf.PageCopyOptions
- Deprecated property `OcgConflictResolution`.
### Pdf.Forms.SignatureField
- New derived classes `DocumentSignature`, `DocMdpSignature`, `DocUrSignature` and `DocumentTimeStamp` to extract properties of digital signatures.
- Replaced property `IsSigned` with derived class `SignedSignatureField`.
- Moved properties `Name` and `Date` to derived class `SignedSignatureField`, because they are only available in signed signature fields.
- Moved properties `Location`, `Reason` and `ContactInfo` to derived class `Signature`, because they are only available in certain types of signed signature fields.
### Pdf.Forms
- New type `MdpPermissions` for the `Permissions` of `DocMdpSignature`.
## Version 3.1
26 November 2021
### Pdf.Content
- New item `All` in enumeration `UngroupingSelection`.
---
## PDF Toolbox SDK for C
The PDF Toolbox SDK for C lets you create PDF files using C.
:::note
For more information on the document model, graphics model, and thread safety, see [About the PDF Toolbox SDK](overview/README.mdx#document-model).
:::
## Namespaces, classes, and methods
In most languages, namespaces and classes are used to model the interfaces. The exception is C, where this is modeled with function prefixes and functions operating on handles.
The PDF Toolbox SDK defines all its used types such as handles and enumerations in the `PdfToolbox_Types.h` header file.
Types are named according to the following naming scheme:
```
T‹prefix›_‹name›
```
where `‹prefix›` is a shortened namespace prefix and `‹name›` is the name of the type.
Similarly, the PDF Toolbox SDK defines functions, collected in header files `PdfToolbox_‹sub-prefix›.h` with the following naming convention:
```
‹prefix›_‹type›_‹name›
```
where `‹type›` is the class name and `‹name›` is the name of the function.
## Library initialization
The first method called must be `Ptx_Initialize`. Failing to invoke this function results in undefined behavior.
Similarly, the last method must be `Ptx_Uninitialize`.
Before calling any of the other functions, a license key must be set by calling `Ptx_Sdk_Initialize`.
## Objects
Objects in the C interface are represented by object handles. Some types are disposable, which means that they must be closed by calling `‹prefix›_‹type›_Close`. All other types must be released by calling `‹prefix›_Release`.
### Type casting
The PDF Toolbox SDK uses a hierarchical class hierarchy, where a parent type
`T‹prefix›_‹parentType›`
can have derived child types
`T‹prefix›_‹childType›`.
Downcasting is necessary. For example, to call the functions of an object’s parent class. In this case, a handle of the child type can be casted using a simple C-style cast:
```
(T‹prefix›_‹parentType›*)pChildTypeHandle
```
Upcasting is also possible using a C-style cast. Prior to casting, the child type of the handle can be determined using
the `GetType` function of the parent class:
```
(T‹prefix›_‹parentType›Type) iChildType = ‹prefix›_‹parentType›_GetType(pParentTypeHandle);
```
## Properties
Properties (a C# term) are modeled with setter and getter functions `‹prefix›_‹type›_Get‹name›` and `‹prefix›_‹type›_Set‹name›`, where `‹name›` is the name of the property.
## Error handling
After having called a function, an error should be detected as follows:
1. If the function’s return type `isBOOL` or a pointer and the return value `isFALSE` or `NULL`, respectively, then an error may have occurred. Then `Ptx_GetLastError` must be called. If this method returns `ePtx_Error_Success`, no error has occurred and the return value is legitimate.
2. If the function’s return type is other than Boolean or a pointer, then `Ptx_GetLastError` must be called. If this method returns `ePtx_Error_Success`, then no error has occurred.
More information about the error can be acquired from `PtxGetLastErrorMessage`.
## Strings
All functions involving strings are provided in two different flavors:
- UTF-16 function with suffix W, using `WCHAR` as parameter type.
- Multi-byte character set function with suffix A, using `char` as parameter type. The concrete character set that is used depends on the platform:
- On Windows, the current ANSI code page (`CP_ACP`) is assumed.
- On Linux or macOS, the current C encoding (`LC_CTYPE`) is used.
In addition to the effective function names with suffix, there’s a macro without suffix for each function pair.
It either resolves to the W variant (if `_UNICODE` is defined), or to the A variant (if `_UNICODE` is not defined).
**Example: Signature of an API string property setter, where `‹String›` stands for the property’s name**
```
// Multibyte encoding:
void ‹prefix›_‹type›_Set‹name›A(T‹prefix›_‹type›* pHandle, const char* szString);
// UTF-16:
void ‹prefix›_‹type›_Set‹name›W(T‹prefix›_‹type›* pHandle, const WCHAR* szString);
#ifdef _UNICODE
#define ‹prefix›_‹type›_Set‹name› ‹prefix›_‹type›_Set‹name›W
#else
#define ‹prefix›_‹type›_Set‹name› ‹prefix›_‹type›_Set‹name›A
#endif
```
### String return values
In C, functions that return a string have a special behavior. Instead of returning the string, those functions take a
buffer and a size as last parameters and write into that buffer. The return value is the amount of data written to the
buffer.
To determine the required buffer size, the function has to be called with `NULL` as buffer argument.
Calling the function with a buffer size that is too small results in an error.
Multi-byte character set functions (with suffix A) that return a string can fail to encode the string in the current operating systems’ encoding. In case of such a failure, the return value is 0 and no error code is set.
To prevent such failures, you should use the UTF-16 (W) functions on Windows or use operating systems with a Unicode code page.
**Example: Signature and usage of an API string property getter (Error handling is omitted)**
```
size_t Ptx_Sdk_GetVersionA(char* pBuffer, size_t nBufferSize);
```
```
size_t nBufferSize = Ptx_Sdk_GetVersionA(NULL, 0);
char* pBuffer = malloc(nBufferSize * sizeof char);
nBufferSize = Ptx_Sdk_GetVersionA(pBuffer, nBufferSize);
```
## Streams
Streams are modeled by means of a set of callbacks and a context pointer, grouped in a struct `TPtxSys_StreamDescriptor`.
An implementation for FILE\* is provided in the header file `PdfToolbox_PtxSys.h`. (Search for function `PtxSysCreateFILEStreamDescriptor`.)
## Arrays
In C, arrays work similarly to strings. Array parameters consist of a pointer to a buffer and a size parameter specifying
the number of array elements.
Functions that return an array take a buffer and a size as last parameters and write into that buffer. The return value is the number of elements written to the buffer. A return value of (size_t)-1 indicates an error.
To determine the required buffer size, the function has to be called with `NULL` as buffer argument.
Calling the function with a buffer size that is too small results in an error.
## Lists
Every list type `T‹prefix›_‹list›` provides a subset of the following functions, where `T‹prefix›_‹eltype›` stands for the type of the contained elements:
| Function | Description | Possible errors |
| ------------------------------------------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------ |
| `int` `‹prefix›_‹list›_GetCount(T‹prefix›_‹list›*)` | Get the number of elements in the list. | `ePtx_Error_IllegalState` |
| `T‹prefix›_‹eltype›*` `‹prefix›_‹list›_Get(T‹prefix›_‹list›*, int index)` | Get an element of the list. | `ePtx_Error_IllegalState`, `ePtx_Error_IllegalArgument`, `ePtx_Error_UnsupportedOperation` |
| `BOOL` `‹prefix›_‹list›_Add(T‹prefix›_‹list›*, T‹prefix›_‹eltype›*)` | Add an element to the end of the list. | `ePtx_Error_IllegalState`, `ePtx_Error_IllegalArgument`, `ePtx_Error_UnsupportedOperation` |
## Enumerables
Enumerables (C# jargon) are lists that only allow iterating. For every enumerable type `T‹prefix›_‹type›`, an additional iterator type `T‹prefix›_‹type›Iterator` is defined. Every enumerable type provides the following function:
| Function | Description | Possible errors |
| ---------------------------------------------------------------------------- | ------------------------------------ | ------------------------- |
| `T‹prefix›_‹type›Iterator*` `‹prefix›_‹type›_GetIterator(T‹prefix›_‹type›*)` | Get an iterator for this enumerable. | `ePtx_Error_IllegalState` |
Every iterator type provides the following functions, where `T‹prefix›_‹eltype›` is the type of the contained
element:
| Function | Description | Possible errors |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| `BOOL` `‹prefix›_‹type›Iterator_MoveNext(T‹prefix›_‹type›Iterator*)` | Move the iterator to the next element. Returns: `1` if the current value is available, `0` if the end has been reached and the current value is `NULL`. | `ePtx_Error_IllegalState` |
| `T‹prefix›_‹eltype›*` `‹prefix›_‹type›Iterator_GetValue(T‹prefix›_‹type›Iterator*)` | Get the current element or NULL if no elements are left. | `ePtx_Error_IllegalState` |
## Maps
A map is a dictionary with unique keys and associated values. Currently, the only keytype in all maps in the API is
a string. Every map type `T‹pre›_‹map›` provides a subset of the following functions, where `T‹pre›_‹eltype›` is the type of the contained values.
| Function | Description | Possible errors |
| ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `int` `‹pre›_‹map›_GetSize(T‹pre›_‹map›*)` | The number of key-value pairs in the map. | `ePtx_Error_IllegalState` |
| `int` `‹pre›_‹map›_GetBegin(T‹pre›_‹map›*)` | Get the position of the first entry in the map. The order of the entries is arbitrary and not significant. If the returned position differs from `‹pre›_‹map›_GetEnd`, then the position can be used to retrieve the map entry with `‹pre›_‹map›_GetKey` and `‹pre›_‹map›_GetValue`. Use `‹pre›_‹map›GetNext` to get the position of the next entry. | `ePtx_Error_IllegalState`, `ePtx_Error_UnsupportedOperation` |
| `int` `‹pre›_‹map›_GetEnd(T‹pre›_‹map›*)` | Get the end position of the map. This position does not correspond to an actual entry in the map. It must be used to determine whether the end of the map has been reached when using `‹pre›_‹map›_GetBegin` and `‹pre›_‹map›_GetNext`. | `ePtx_Error_IllegalState`, `ePtx_Error_UnsupportedOperation` |
| `int` `‹pre›_‹map›_GetNext(T‹pre›_‹map›*, int it)` | Get the position of the next entry in the map. The order of the entries is arbitrary and not significant. If the returned position differs from `‹pre›_‹map›_GetEnd`, then the position can be used to retrieve the map entry with `‹pre›_‹map›_GetKey` and `‹pre›_‹map›_GetValue`. | `ePtx_Error_IllegalState`, `ePtx_Error_UnsupportedOperation` |
| `int` `‹pre›_‹map›_GetA(T‹pre›_‹map›*, const char* szKey)` | Get the position of a key in the map. If no error occurred, then the position can be used to get the corresponding value with `‹pre›_‹map›_GetValue`. | `ePtx_Error_IllegalState`, `ePtx_Error_UnsupportedOperation`, `ePtx_Error_IllegalArgument`, `ePtx_Error_NotFound` |
| `size_t` `‹pre›_‹map›_GetKeyA(T‹pre›_‹map›*, int it, char*, size_t)` | Get the key of the entry given a position. | `ePtx_Error_IllegalState`, `ePtx_Error_UnsupportedOperation`, `ePtx_Error_IllegalArgument` |
| `T‹pre›_‹eltype›* ‹pre›_‹map›_GetValue(T‹pre›_‹map›*, int it)` | Get the value of the entry given a position. | `ePtx_Error_IllegalState`, `ePtx_Error_UnsupportedOperation`, `ePtx_Error_IllegalArgument` |
| `BOOL` `‹pre›_‹map›_SetA(T‹pre›_‹map›*, const char* szKey, T‹pre›_‹eltype›* pValue)` | Set the value of an entry for a given key. This operation invalidates all positions previously returned by `‹pre›_‹map›_GetBegin`, `‹pre›_‹map›_GetEnd`, `‹pre›_‹map›_GetNext`, and `‹pre›_‹map›_Get`. | `ePtx_Error_IllegalState`, `ePtx_Error_UnsupportedOperation`, `ePtx_Error_IllegalArgument` |
| `BOOL` `‹pre›_‹map›_SetValue(T‹pre›_‹map›*, int it, T‹pre›_‹eltype›* pValue)` | Set the value of the entry at a position in the map. | `ePtx_Error_IllegalState`, `ePtx_Error_UnsupportedOperation`, `ePtx_Error_IllegalArgument` |
| `BOOL` `‹pre›_‹map›_Clear(T‹pre›_‹map›*)` | Remove all entries from the map. | `ePtx_Error_IllegalState`, `ePtx_Error_UnsupportedOperation`, `ePtx_Error_IllegalArgument` |
| `BOOL` `‹pre›_‹map›_Remove(T‹pre›_‹map›*, int it)` | Remove the entry at a position in the map. | `ePtx_Error_IllegalState`, `ePtx_Error_UnsupportedOperation`, `ePtx_Error_IllegalArgument` |
---
## PDF Toolbox SDK for .NET
The PDF Toolbox SDK for .NET lets you create PDF files using .NET.
:::note
For more information on the document model, graphics model, and thread safety, see [About the PDF Toolbox SDK](overview/README.mdx#document-model).
:::
:::tip
For the full API reference for the PDF Toolbox SDK, see the [.NET API reference](https://api-reference.pdf-tools.com/toolsdk/4.3/dotnet/html/R_Project_API_Reference.htm).
:::
## IDisposable objects
Objects that must be closed explicitly (such as those based on `Document,` `ContentGenerator`, and `TextGenerator` classes) implement the `IDisposable` interface. Instead of calling `Dispose()` directly, it is recommended that you use the “using” statement:
```
using (Document document = ...)
{
...
}
// document.Dispose() is called implicitly here
```
See also [Garbage collection and closing objects](/overview/README.mdx#thread-safety).
## Error handling
Errors are reported using exceptions.
The following logic errors are mapped to the corresponding native exception classes:
- `IllegalArgument` maps to `System.ArgumentException`
- `IllegalState` maps to `System.InvalidOperationException`
- `UnsupportedOperation` maps to `System.NotSupportedException`
Additionally, the following infrastructure error is mapped:
- `IO` maps to `System.IO.IOException`
The remaining errors are modeled using exception classes that inherit from the class `PdfToolboxException`.
## Streams
The native stream interface `System.IO.Stream` is used.
## Lists
Lists implement the native list interface `System.Collections.Generic.IList`.
## Enumerables
Enumerables implement the native interface `System.Collection.Generic.IEnumerable`.
## Maps
Maps implement the native dictionary interface `System.Collections.Generic.IDictionary`.
---
## PDF Toolbox SDK for Java
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
The PDF Toolbox SDK for Java lets you create PDF files using Java.
:::info
The PDF Toolbox SDK for Java requires **Java version 7 or higher**.
:::
:::note
For more information on the document model, graphics model, and thread safety, see [About the PDF Toolbox SDK](overview/README.mdx#document-model).
:::
:::tip
For the full API reference for the PDF Toolbox SDK, see the [Java API reference](https://api-reference.pdf-tools.com/toolsdk/4.3/javadoc/index.html?overview-summary.html).
:::
## Compilation
When using the Java interface, the Java archive `jar\com.pdf_tools.fourheights.pdftoolbox.jar` needs to be on the `CLASSPATH`. This can be done by either adding
it to the environment variable `CLASSPATH`, or by specifying it using the `-classpath` or `-cp` switch:
```
javac -cp ".;C:\Program Files\PDF Tools AG\jar\com.pdf_tools.fourheights.pdftoolbox.jar" ^
sampleApplication.java
```
```
javac -cp ".:/path/to/com.pdf_tools.fourheights.pdftoolbox.jar" ^
sampleApplication.java
```
```
javac -cp ".:/path/to/com.pdf_tools.fourheights.pdftoolbox.jar" ^
sampleApplication.java
```
## Execution
Additionally, the library needs to be in one of the system’s library directories or added to the Java system property `java.library.path`.
In Windows, the library is defined by the environment variable `PATH`.
On Linux, the library is defined by `LD_LIBRARY_PATH`.
In macOS, the library is defined by `LD_LIBRARY_PATH`.
This can be achieved by either adding this system property dynamically at program startup before using the API, or by specifying it using the switch `-Djava.library.path` when starting the Java VM.
Choose the correct subdirectory (`win-x64` or `win-x86` on Windows) depending on the platform of the Java VM3. If the wrong data model is used, there is an error message similar to this: “Can't load IA 32-bit .dll on a AMD 64-bit platform”.
```
java -cp ".;C:\Program Files\PDF Tools AG\com.pdf_tools.fourheights.pdftoolbox.jar" ^
"-Djava.library.path=C:\Program Files\PDF Tools AG\lib\win-x64" sampleApplication
```
In Linux, the path separator usually is a colon, so use:
```
java -cp ".:/path/to/com.pdf_tools.fourheights.pdftoolbox.jar" ^
"-Djava.library.path=/opt/pdftools.com/lib/linux-x64" sampleApplication
```
The path separator usually is a colon, so use:
```
java -cp ".:/path/to/com.pdf_tools.fourheights.pdftoolbox.jar" ^
"-Djava.library.path=/opt/pdftools.com/lib/osx-arm64" sampleApplication
```
## AutoCloseable objects
Objects that must be closed explicitly implement the `AutoCloseable` interface. Instead of calling `close()` directly, it is recommended that you use the “try with resources” statement:
```
try (Document document = ...) {
...
} // document.close() is called implicitly here
```
See also [Garbage collection and closing objects](/overview/README.mdx#thread-safety).
## Properties
Properties are modeled with setter and getter methods.
## Error handling
Errors are reported using exceptions.
The following logic errors are mapped to the corresponding native runtime exception classes and are not checked:
- `IllegalArgument` maps to `java.lang.IllegalArgumentException`
- `IllegalState` maps to `java.lang.IllegalStateException`
- `UnsupportedOperation` maps to `java.lang.UnsupportedOperationException`
Additionally, the following infrastructure error is mapped:
- `IO` maps to `java.io.IOException`
The remaining errors are modeled using exception classes that inherit from a base class `PdfToolboxException`.
## Streams
The native stream interfaces cannot be used, because they are lacking two important features:
- The PDF file format is based on random access. Native Java streams have only limited support for this.
- The ability to read from an output stream is crucial for processing large files.
Instead, a custom stream interface `com.pdf_tools.fourheights.pdftoolbox.Stream` is provided.
A `FileStream` implementation for files is provided, backed by `java.io.RandomAccessFile`.
For in-memory processing, a `MemoryStream` implementation is provided.
## Lists
Lists implement the native Java list interface `java.util.List`.
## Enumerables
Enumerables (lists that only allow iterating) implement the native Java iterator interface `java.util.Iterable`.
## Maps
Maps implement the native Java map interface `java.util.Map`.
---
## Use the PDF Toolbox SDK
import DocCardList from '@theme/DocCardList';
Learn about the most commonly used PDF Toolbox SDK features and find sample projects that help you integrate them.
`) are used when the elements are already in memory and random access is possible. Depending on the context, manipulation (add, remove, and so on) might also be possible.
- Iterables (`System.Collection.Generic.IEnumerable`) are used when elements are retrieved on demand. They don't allow random access, but only allow iterating through the elements.
## Maps
Maps implement the native dictionary interface `System.Collections.Generic.IDictionary`.
## Namespace
The Pdftools SDK uses the namespace `PdfTools`.
:::note
We recommend using a custom, company-specific namespace for your code.
Using the `PdfTools` namespace like the SDK can lead to problems with ambiguous class names, especially when you use multiple Pdftools SDKs in the same project.
:::
---
## General technical notes
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
This documentation explains how the Pdftools SDK interacts with your local operating system to [locate fonts](#locating-fonts), [locate color profiles](#locating-color-profiles), and store [temporary files](#temporary-files-directory) and [cache files](#cache-directory).
{/* TODO turn this into landing page with cards / a grid for release notes, technical notes, and API references (in all languages)
C Java .NET Release notes
general technical notes ... ... ... n/a
tools sdk ... ... ... ...
toolbox ... ... ... ...
... = a link to a section / subpage
*/}
## Locating fonts
Some Pdftools SDK features require fonts to be installed locally.
For example, the PDF/A standard requires all fonts to be embedded in the PDF file. If non-embedded fonts are used in the original PDF, the fonts must be embedded during conversion to PDF/A. To embed fonts, a matching font has to be located in the [font directories](#font-directories).
### Font directories
The location of the font directories depends on the operating system.
The SDK traverses font directories recursively in the order specified. If two fonts with the same name are found, the latter takes precedence. As a result, user fonts always take precedence over system fonts.
#### Installing fonts on Windows
By default, Windows installs fonts only for a particular user.
Either install fonts for all users or make sure you run the
Pdftools SDK under that user and load the user profile.
The font directories for Windows are:
1. `%SystemRoot%\Fonts`
2. User fonts listed in the registry key:
```
\HKEY_CURRENT_USER\Software\Microsoft\Windows NT\CurrentVersion\Fonts
```
Fonts listed in the registry key include user specific fonts from:
```
C:\Users\\AppData\Local\Microsoft\Windows\Fonts
```
Also, app specific fonts from:
```
C:\Program Files\WindowsApps
```
3. `Fonts` directory, which must be a direct subdirectory of where `PdfToolsSdkAPI.dll` resides.
The SDK traverses the directories recursively in this order.
#### Installing fonts on Linux and Debian systems
On Linux, install the Liberation fonts, Google Noto CJK fonts, and the OpenSymbol font.
On Debian-based systems, the packages are `fonts-liberation2`, `fonts-noto-cjk`, and `fonts-opensymbol`.
Many PDF documents use Microsoft core fonts such as Arial, Times New Roman, and other fonts commonly used on Windows. Therefore, install these fonts to your default font directories.
Linux distributions often offer an installable package for Microsoft TrueType core fonts. For instance, on Debian-based systems, the package is `ttf-mscorefonts-installer`. Alternatively, you can download the fonts from [SourceForge Core Fonts](http://corefonts.sourceforge.net/).
For more information on Microsoft core fonts and licensing, see [Font redistribution FAQ for Windows](https://docs.microsoft.com/en-us/typography/fonts/font-faq).
**The font directories for Linux are the following:**
1. `/usr/share/fonts`
2. `/usr/local/share/fonts`
3. `~/.fonts`
4. `/usr/lib/X11/fonts/Type1`, which can be overridden by setting the environment variable `PDFFONTDIR`.
The SDK traverses the directories recursively in this order.
#### Installing fonts on macOS
On macOS, install the Liberation fonts, Google Noto CJK fonts, and the OpenSymbol font.
Many PDF documents use Microsoft core fonts such as Arial, Times New Roman, and other fonts commonly used on Windows. Therefore, install these fonts to your default font directories. You can download the fonts from [SourceForge Core Fonts](http://corefonts.sourceforge.net/).
For more information on Microsoft core fonts and licensing, see [Font redistribution FAQ for Windows](https://docs.microsoft.com/en-us/typography/fonts/font-faq).
**The font directories for macOS are the following:**
1. `/System/Library/Fonts`
2. `/Library/Fonts`
The SDK traverses the directories recursively in this order.
### Adding custom font lookup paths
In addition to the directories listed above, developers can specify custom font lookup paths using the following methods:
* C: [PdfTools_Sdk_AddFontDirectoryA](https://api-reference.pdf-tools.com/pdfsdk/1.13/cdoc/_pdf_tools___pdf_tools_8h.html#afb5780e0a309889566e945040deffb74) or [PdfTools_Sdk_AddFontDirectoryW](https://api-reference.pdf-tools.com/pdfsdk/1.13/cdoc/_pdf_tools___pdf_tools_8h.html#a8b13e5d769c96c96edf4af36c57c6dbc)
* C#: [Sdk.AddFontDirectory](https://api-reference.pdf-tools.com/pdfsdk/1.13/dotnet/html/M_PdfTools_Sdk_AddFontDirectory.htm)
* Java: [Sdk.addFontDirectory](https://api-reference.pdf-tools.com/pdfsdk/1.13/javadoc/com/pdftools/Sdk.html#addFontDirectory(java.lang.String))
* Python: [sdk.add_font_directory](https://api-reference.pdf-tools.com/pdfsdk/1.13/pydocs/_autosummary/pdftools_sdk.sdk.html#pdftools_sdk.sdk.Sdk.add_font_directory)
### Font cache
A cache of all fonts in all font directories is created. If fonts are added or removed from the font directories, the cache is updated automatically.
To achieve optimal performance, make sure that the cache directory is writable for the Pdftools SDK. Otherwise, the font cache cannot be updated and the font directories have to be scanned on each program startup.
The font cache is created in the subdirectory `/Installed Fonts` of the cache directory.
## Locating color profiles
If no color profiles are available, default profiles for both RGB and CMYK are generated on the fly by the Pdftools SDK. If no specific color profiles are set, default profiles are used. By default, the SDK uses the color profile "sRGB Color Space Profile.icm" for device RGB colors, and "USWebCoatedSWOP.icc" for device CMYK. It searches for these profiles in the specified directories:
1. `%SystemRoot%\System32\spool\drivers\color`
2. directory `Icc`, which must be a direct sub-directory of where the `PdfToolsSdkAPI.dll` resides.
1. `$PDF_ICC_PATH` if the environment variable is defined
2. the current working directory
1. `$PDF_ICC_PATH` if the environment variable is defined
2. the current working directory
Most systems have pre-installed color profiles. For example, on Windows at `%SystemRoot%\system32\spool\drivers\color\`.
You can download color profiles from the links provided in the `bin\Icc\` directory or from these websites:
- [Pdftools color profiles](http://www.pdf-tools.com/public/downloads/resources/colorprofiles.zip)
- [ICC sRGB profiles](http://www.color.org/srgbprofiles.html)
- [Adobe ICC Profiles](https://www.adobe.com/support/downloads/iccprofiles/iccprofiles_win.html)
## Special directories
The Pdftools SDK uses special directories during file processing. For optimal performance, the application should have write access to these directories.
### Temporary files directory
The directory of temporary files is used for data specific to one instance of a program. The data isn't shared between different invocations and is deleted after the program is terminated.
The SDK determines the directory as follows by checking for the existence of environment variables in the following order and using the first path found:
1. The path specified by the `%TMP%` environment variable.
2. The path specified by the `%TEMP%` environment variable.
3. The path specified by the `%USERPROFILE%` environment variable.
4. The Windows directory.
1. The path specified by the `$PDFTMPDIR` environment variable.
2. The path specified by the `$TMP` environment variable.
3. The `/tmp` directory.
1. The path specified by the `$PDFTMPDIR` environment variable.
2. The path specified by the `$TMP` environment variable.
3. The `/tmp` directory.
### Cache directory
The cache directory is used for data that persists and is shared between different invocations of a program. The SDK creates the actual caches in subdirectories. You can safely delete the content of this directory to clean all caches.
The application must be able to write to this directory. Otherwise, the SDK can't create or update caches, leading to significantly decreased performance.
If the user has a profile:
```
%LOCAL_APPDATA%\PDF Tools AG\Caches
```
If the user has no profile:
```
\PDF Tools AG\Caches
```
If the user has a home directory:
```
~/.pdf-tools/Caches
```
If the user has no home directory:
```
/pdf-tools/Caches
```
The `` refers to the [directory for temporary files](#temporary-files-directory).
If the user has a home directory:
```
~/.pdf-tools/Caches
```
If the user has no home directory:
```
/pdf-tools/Caches
```
The `` refers to the [directory for temporary files](#temporary-files-directory).
---
## Java technical notes
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
Learn about technical details of the Pdftools SDK for Java.
:::tip
For the full API reference for the Pdftools SDK, see the [Java API reference](https://pdf-tools.com/docs/pdf-tools-sdk/api-reference/latest/javadoc/index.html?overview-summary.html).
:::
## AutoCloseable objects
Objects that must be closed explicitly (for example, `com.pdftools.pdf.Document`, `com.pdftools.image.Document`, `com.pdftools.crypto.providers.Provider`, or subclasses) implement the `java.lang.AutoCloseable` interface. Instead of calling `close()` directly, use the "try-with-resources" statement:
```
try (Document document = ...) {
...
} // document.close() is called implicitly here
```
{/* TODO readd this if we decide to add the additional documents analog to the toolbox
See also [Garbage collection and closing objects](#thread-safety).
*/}
## Properties
Properties are modeled with setter and getter methods.
## Error handling
Errors are reported using exceptions.
Where applicable, the SDK maps errors to corresponding native runtime exceptions, such as `java.lang.IllegalArgumentException`, `java.lang.IllegalStateException`, `java.lang.UnsupportedOperationException`, or `java.io.IOException`.
The remaining errors are modeled using exception classes that inherit from a base class `PdfToolsException`.
## Streams
The native stream interfaces can't be used because they're lacking two important features:
- The PDF file format is based on random access. Native Java streams have only limited support for this.
- The ability to read from an output stream is crucial for processing large files.
Instead, a custom stream interface `com.pdftools.sys.Stream` is provided.
A `FileStream` implementation for files is provided, backed by `java.io.RandomAccessFile`.
For in-memory processing, a `MemoryStream` implementation is provided.
## Lists and iterables
The API uses different concepts for returning collections of elements depending on the context:
- Lists (`java.util.List`) are used when the elements are already in memory and random access is possible. Depending on the context, manipulation (add, remove, and so on) might also be possible.
- Iterables (`java.util.Iterable`) are used when elements are retrieved on demand. They don't allow random access, but only allow iterating through the elements.
## Maps
Maps implement the native Java map interface `java.util.Map`.
## Package
The Pdftools SDK uses the package `com.pdftools`.
:::note
We recommend using a custom, company-specific package for your code.
Using the `com.pdftools` package like the SDK can lead to problems with ambiguous class names, especially when you use multiple Pdftools SDKs in the same project.
:::
---
## Archive with the Pdftools SDK
With the Pdftools SDK you can archive files to the following formats:
- [Archive a PDF document to PDF/A](#archive-pdf-to-pdfa)
- [Archive images to accessible PDF/A](#archive-images-to-accessible-pdfa)
- [Archive PDF to TIFF image archive](#archive-pdf-to-tiff-image-archive)
---
## Archive PDF to PDF/A
With the Pdftools SDK, you can convert PDF documents to [PDF/A specification](/docs/knowledge/pdf-a/) (PDF/A-1, PDF/A-2, PDF/A-3), including all conformance levels (B, A, and U).
You can read encrypted documents, repair or recover corrupt data and objects.
You can remove content and convert embedded and attached files.
:::note Accepted formats
| Input format | Output format |
|---|---|
| PDF 1.x, PDF 2.0 | PDF/A-1b, PDF/A-1a, PDF/A-2b, PDF/A-2a, PDF/A-2u, PDF/A-3b, PDF/A-3a, PDF/A-3u |
:::
**Input document processing**
- Automatically determine optimal conformance based on input file (optional)
- Recover corrupt documents
- Repair corrupt data such as embedded font programs or images
- Repair metadata and make them consistent
**Color management and fonts**
- Make color spaces device-independent, e.g. by embedding ICC profile or setting an output intent
- Manage colorants (PDF/A-2 and later)
- Embed and subset fonts
**Conversion process**
- Control the conversion process with pre- and post-validation, conversion reports, and application log files
- Remove transparency (PDF/A-1 only)
- Remove malicious content such as attached files (PDF/A-1 and PDF/A-2) and JavaScript actions
- Remove multimedia content such as video and sound
- Convert embedded and attached files (PDF/A-2 and later)
:::tip Get started
Learn how to **[archive a PDF file to a PDF/A format](archive-pdf-pdfa.mdx)**.
:::
---
## Archive images to accessible PDF/A
Convert one or more single-page or multi-page raster images to an output PDF document with searchable text.
:::note Accepted formats
| Input | Output |
| -------------------------------------------- | ---------------------------- |
| TIFF, JPEG, BMP, GIF, PNG, JBIG2 or JPEG2000 | PDF/A-1a, PDF/A-2a, PDF/A-3a |
:::
**Image processing**
- Select image compression, depending on the image type
- Select image quality for lossy compression
- Set standard resolution (DPI / X and Y coordinates)
- Choose optional JPEG image recompression
**Page layout**
- Select PDF page size or determine automatically
- Select page area
- Set scaling
- Set image position
- Set image orientation (portrait or landscape)
**PDF document settings**
- Set encryption and user access permissions
- Set document attributes
- Select and embed ICC color profiles
- Define alternative text (tagging) and image language
- Embed XMP metadata
:::tip Get started
Learn how to **[archive an image to an accessible PDF/A document](archive-image-pdfa-accessible.mdx)**.
:::
## Archive PDF to TIFF image archive
Convert PDFs to TIFF images in a format suitable for archiving using the [Archive conversion profile](../convert/conversion-profiles.mdx#archive).
:::note Accepted formats
| Input | Output |
| ------------------------------------------- | --------------- |
| PDF 1.x, PDF 2.0, PDF/A-1, PDF/A-2, PDF/A-3 | TIFF |
:::
**Image processing**
- Set resolution (DPI)
- Set TIFF file compression algorithm
- Set the quality of lossy image compression
**Color management**
- Set background color
- Set color space
**Page layout**
- Define page dimensions in standard page sizes, points or pixels
- Set rotation: force portrait or landscape or inherit rotation from original document
:::tip Get started
Learn how to **[Archive PDF document to TIFF image archive](archive-pdf-tiff.mdx)**.
:::
## Archive conversion profile
Conversion profiles define how an input file is converted and rendered in an output file. A profile contains a set of conversion parameters that are combined for a practical use case.
For more information, see [Conversion profiles](../convert/conversion-profiles.mdx) documentation.
---
## Archive an image to an accessible PDF
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
Valid PDF/A documents with A-level (Accessibility) conformance (PDF/A-1a, PDF/A-2a, PDF/A-3a) must have text that can be reliably searched and copied. The content structure in the accessible PDF/A document can be accessed by technologies such as screen readers.
:::tip Quick start with a code sample
Download the full sample now in **[C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Img2PdfAccessibility/Download?technology=CS)**, **[Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Img2PdfAccessibility/Download?technology=Java)**, **[Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Img2PdfAccessibility/Download?technology=Python)**, and **[Visual Basic](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Img2PdfAccessibility/Download?technology=VB)**.
Interested in C, Go, Rust or other programming language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.
:::
When archiving an image to a PDF/A document with A-level conformance, descriptive text must be provided for each page that is added to the document.
For example, "This color image shows a small sailing boat at sunset".
The language of the text must also be provided in ISO 3166:2013 format.
For example, "en" or "de-CH".
For scanned text documents, the [Conversion Service](/docs/conversion-service/) can be used to recognize the characters in the documents (OCR) and tag the image with the recognized structure and text.
:::info
For more background about converting images to PDF documents, see [Convert an image to a PDF document](../convert/convert-image-pdf.mdx).
:::
**Steps to archive a document**
1. [Reading the input image](#reading-the-input-image)
2. [Selecting a conversion profile](#selecting-a-conversion-profile)
3. [Specifying the conformance level](#specifying-the-conformance-level)
4. [Adding accessible content](#adding-accessible-content)
5. [Converting the image to a PDF document](#converting-the-image-to-a-pdf-document)
6. [Full example](#full-example)
---
:::note Before you begin
You need to **[initialize the library](/docs/licenses/products/pdf-tools-sdk-license/#activate-the-pdftools-sdk-license)**.
:::
## Reading the input image
First you need to read the image you want to convert. To do this, load the input image from the file system into a read-only image `Document`.
This `Document` can then later be passed to the `Converter`.
```csharp
// Open image document
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);
```
```java
// Open input document
FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
com.pdftools.image.Document inDoc = com.pdftools.image.Document.open(inStr);
```
## Selecting a conversion profile
You start the image conversion process by creating a conversion `Profile` object.
The `Profile` object defines the parameters that are applied to the conversion process.
This example uses the `Archive` profile, which is intended for document workflows that convert images to PDF/A documents for archiving.
```csharp
/// Create the profile that defines the conversion parameters.
// The Archive profile converts images to PDF/A documents for archiving.
var profile = new Profiles.Archive();
```
```java
// Create the profile that defines the conversion parameters.
// The Archive profile converts images to PDF/A documents for archiving.
Archive profile = new Archive();
```
## Specifying the conformance level
By default, the `Archive` profile produces output PDF documents with PDF/A-2b conformance.
If the document workflow requires accessible content to be included in the output PDF, then conformance Level A (Accessible) should be used instead.
This examples sets the document conformance to PDF/A-2a.
```csharp
// Set conformance of output document to PDF/A-2a
profile.Conformance = new Conformance(2, Conformance.PdfALevel.A);
```
```java
// Set conformance of output document to PDF/A-2a
profile.setConformance(new Conformance(new Conformance.PdfAVersion(2, Level.A)));
```
## Adding accessible content
For each page created in the output PDF/A document, alternate text must be added that represents the contents of the image on that page.
In addition, the language of the text should be specified at a document level.
```csharp
// For PDF/A level 2a, an alternate text is required for each page of the image.
// This is optional for other PDF/A levels, e.g. PDF/A-2b.
profile.Language = "en";
profile.AlternateText.Add(alternateText);
```
```java
// For PDF/A level A, an alternate text is required for each page of the image.
// This is optional for other PDF/A levels, e.g. PDF/A-2b.
profile.setLanguage("en");
profile.getAlternateText().add(alternateText);
```
## Converting the image to a PDF document
After setting the appropriate `Profile` and `Conformance` levels, and adding accessible content, the final step is to instantiate a `Converter` object and call its `Convert` method.
The output PDF/A document is created at the specified path.
```csharp
// Create output stream
using var outStr = File.Create(outPath);
// Convert the image to a tagged PDF/A document
using var outDoc = new Converter().Convert(inDoc, outStr, profile);
```
```java
// Create output stream
FileStream outStream = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW);
// Convert the image to a tagged PDF/A document
com.pdftools.pdf.Document outDoc = new Converter().convert(inDoc, outStream, profile));
```
## Full example
{/*sample source: PdfToolsSDK/Samples/Templates/img2pdfaccessibility.cs*/}
```csharp
// Open image document
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);
// Create the profile that defines the conversion parameters.
// The Archive profile converts images to PDF/A documents for archiving.
var profile = new Profiles.Archive();
// Set conformance of output document to PDF/A-2a
profile.Conformance = new Conformance(2, Conformance.PdfALevel.A);
// For PDF/A level 2a, an alternate text is required for each page of the image.
// This is optional for other PDF/A levels, e.g. PDF/A-2b.
profile.Language = "en";
profile.AlternateText.Add(alternateText);
// Create output stream
using var outStr = File.Create(outPath);
// Convert the image to a tagged PDF/A document
using var outDoc = new Converter().Convert(inDoc, outStr, profile);
```
{/*sample source: PdfToolsSDK/Samples/Templates/img2pdfaccessibility.java*/}
```java
// Create the profile that defines the conversion parameters.
// The Archive profile converts images to PDF/A documents for archiving.
Archive profile = new Archive();
// Set conformance of output document to PDF/A-2a
profile.setConformance(new Conformance(new Conformance.PdfAVersion(2, Level.A)));
// For PDF/A level A, an alternate text is required for each page of the image.
// This is optional for other PDF/A levels, e.g. PDF/A-2b.
profile.setLanguage("en");
profile.getAlternateText().add(alternateText);
// Optionally, other profile parameters can be changed according to the
// requirements of your conversion process.
try (
// Open input document
FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
com.pdftools.image.Document inDoc = com.pdftools.image.Document.open(inStr);
// Create output stream
FileStream outStream = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW);
// Convert the image to a tagged PDF/A document
com.pdftools.pdf.Document outDoc = new Converter().convert(inDoc, outStream, profile))
{
}
```
---
## Archive a PDF document to PDF/A
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
The Pdftools SDK lets you archive a PDF document so that it meets a defined PDF/A standard and conformance level, making the minimum changes necessary to the PDF structure and objects so it complies.
It provides detailed information about any changes that were made during the conversion process.
:::tip Quick start with a code sample
Download the full sample now in **[C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/ValidateConvert/Download?technology=C)**, **[C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/ValidateConvert/Download?technology=CS)**, **[Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/ValidateConvert/Download?technology=Java)**, **[Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/ValidateConvert/Download?technology=Python)**, and **[Visual Basic](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/ValidateConvert/Download?technology=VB)**.
Interested in Go, Rust or other programming language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.
:::
The Pdftools SDK supports conversion to the following PDF/A standards:
- PDF/A-1 (ISO 19005-1)
- PDF/A-2 (ISO 19005-2)
- PDF/A-3 (ISO 19005-3)
Within the PDF/A standards, the following conformance levels are supported:
- B (Basic)
- U (Unicode, only PDF/A-2 and PDF/A-3)
- A (Accessibility)
:::info
For more information about supported PDF/A standards, review [PDF/A overview](/docs/knowledge/pdf-a/).
:::
**Steps to archive a document**:
1. [Reading the input document](#reading-the-input-document)
2. [Creating a Conformance object](#creating-a-conformance-object)
3. [Creating a Validator object](#creating-a-validator-object)
4. [Running the Analyze method](#running-the-analyze-method)
5. [Creating a Converter object](#creating-a-converter-object)
6. [Running the Convert method](#running-the-convert-method)
7. [Checking the conversion results](#checking-the-conversion-results)
8. [Full example](#full-example)
---
:::note Before you begin
You need to **[initialize the library](/docs/licenses/products/pdf-tools-sdk-license/#activate-the-pdftools-sdk-license)**.
:::
## Reading the input document
First you need to read the PDF document you want to archive. To do this, load the input document from the file system into a read-only PDF `Document`.
This `Document` can then later be passed to the `Validator` and `Converter`.
```csharp
// Open image document
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);
```
```java
// Open input document
FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
com.pdftools.pdf.Document inDoc = com.pdftools.pdf.Document.open(inStr);
```
## Creating a Conformance object
The document conversion process begins with the creation of a `Conformance` object.
The `Conformance` object defines the PDF/A standard and level to which the output document must conform.
This example uses the PDF/A-2 standard (`2`), with conformance level B (`Conformance.PdfALevel.B`).
```csharp
// Create a Conformance object that specifies the PDF/A level against which the document is to be validated prior to conversion.
// Here, PDF/A-2b is specified.
Conformance conformance = new Conformance(2, Conformance.PdfALevel.B);
```
```java
// Create a Conformance object that specifies the PDF/A level against which the document is to be validated prior to conversion.
// Here, PDF/A-2b is specified.
Conformance conformance = new Conformance(new Conformance.PdfAVersion(2, Conformance.PdfAVersion.Level.B));
```
## Creating a Validator object
The `Validator` object analyzes the conformance of the input PDF document with the PDF/A standard and level defined in the `Conformance` object.
This step is similar to the first step of the [PDF/A validation process](../validate/validate-a-pdf.mdx).
However, during the PDF/A conversion process, additional information is also generated about the _potential_ conformance level of the document.
```csharp
// Create the Validator object, and use the Conformance object to create
// an AnalysisOptions object that controls the behavior of the Validator.
var validator = new Validator();
var analysisOptions = new AnalysisOptions() { Conformance = conformance };
```
```java
// Create the Validator object, and use the Conformance object to create
// an AnalysisOptions object that controls the behavior of the Validator.
Validator validator = new Validator();
AnalysisOptions analysisOptions = new AnalysisOptions();
analysisOptions.setConformance(conformance);
```
## Running the Analyze method
In addition to evaluating the document's conformance with the defined PDF/A standard and level, the `Analyze` method also provides a recommendation on whether the input document _should_ be converted to PDF/A.
The `Analyze` method recommends conversion in the following cases:
- If `IsConforming` is `false`, i.e., if the document does not conform to the required `Conformance`.
- If the document is conforming, but there are other issues where conversion is highly recommended.
For example, if corner-cases of the PDF/A specification that are known to cause problems for PDF viewers are detected.
When conversion is recommended, the recommended output PDF/A standard and level is provided in the `RecommendedConformance` value of the `AnalysisResult` object.
This `RecommendedConformance` is the highest possible PDF/A level to which the document can conform.
Setting a higher level for the conversion typically results in a conformance exception.
Even if the `RecommendedConformance` is higher than the `Conformance` passed to the `AnalysisOptions`, you do not need to increase the level of the `Conformance` passed to the `ConversionOptions`, because this level is automatically updated to the highest achievable level.
Therefore, you can always set the `Conformance` provided in the `AnalysisOptions` to the lowest acceptable level.
```csharp
// Run the analysis, and check the results.
// Only proceed if document is not conforming.
var analysisResult = validator.Analyze(inDoc, analysisOptions);
if (analysisResult.IsConversionRecommended) {
return; // No conversion is required.
}
```
```java
// Run the analysis, and check the results.
// Only proceed if document is not conforming.
AnalysisResult analysisResult = validator.analyze(inDoc, analysisOptions);
if (analysisResult.getIsConversionRecommended())
{
return; // No conversion is required.
}
```
## Creating a Converter object
The `Converter` object converts the input PDF document into an output document that conforms to the defined PDF/A standard and level.
When the `Converter` makes changes to the document during the conversion process, it emits `ConversionEvent` events that provide detailed information about the type of change and where the change has been made in the output PDF/A document.
Even if the output document meets all required standards, the conversion may have resulted in differences that are acceptable in some processes, but not in others.
Because of this, a handler function should listen to the `ConversionEvent` events and execute business logic based on the information contained in them.
Each `ConversionEvent` has a `Severity` that indicates the following types of changes were made to the output document:
1. **Information:** Changes were made, but the change had no visible impact on the document.
2. **Warning:** Changes were made that may have visible impacts. Check the output file to decide if the result is acceptable.
3. **Error:** Changes were not successful. The document could not be converted to the desired conformance level.
You should check for the highest `EventSeverity` that occurred during the conversion, as it makes it easier to troubleshoot errors later.
```csharp
// Create a converter object
var converter = new Converter();
// Add handler for conversion events
var eventsSeverity = EventSeverity.Information;
converter.ConversionEvent += (s, e) =>
{
// Get the event's suggested severity
var severity = e.Severity;
// Optionally, the suggested severity can be changed according to
// the requirements of your conversion process and, for example,
// the event's category (e.Category).
if (severity > eventsSeverity)
eventsSeverity = severity;
// Report conversion event
Console.WriteLine("- {0} {1}: {2} ({3}{4})",
severity.ToString()[0], e.Category, e.Message, e.Context, e.PageNo > 0 ? " page " + e.PageNo : ""
);
};
```
```java
// Create a converter object
Converter converter = new Converter();
// Add handler for conversion events
class EventListener implements ConversionEventListener
{
private EventSeverity eventsSeverity = EventSeverity.INFORMATION;
public EventSeverity getEventsSeverity() {
return eventsSeverity;
}
@Override
public void conversionEvent(ConversionEvent event) {
// Get the event's suggested severity
EventSeverity severity = event.getSeverity();
// Optionally, the suggested severity can be changed according to
// the requirements of your conversion process and, for example,
// the event's category (e.Category).
if (severity.ordinal() > eventsSeverity.ordinal())
eventsSeverity = severity;
// Report conversion event
System.out.format("- %c %s: %s (%s%s)%n", severity.toString().charAt(0), event.getCategory(), event.getMessage(), event.getContext(), event.getPageNo() > 0 ? " on page " + event.getPageNo() : "");
}
}
EventListener el = new EventListener();
converter.addConversionEventListener(el);
```
## Running the Convert method
After generating the `AnalysisResult` and creating the `Converter` objects, the final step is to call the `Convert` method.
By default, the `Converter` object attempts to convert the input PDF document to the PDF/A standard and level defined in the `RecommendedConformance` value in the `AnalysisResult`.
It is possible to override this behavior and force conversion to a different PDF/A standard and level.
You can force conversion by passing an optional `ConversionOptions` parameter to the `Convert` method.
When `ConversionOptions` are passed to the `Convert` method but the required conformance level cannot be achieved, conversion aborts with a `ConformanceException`.
```csharp
// Create a stream for the output PDF/A file.
using var outStr = File.Create(outPath);
// Convert the input document to the recommended conformance level using the converter object.
using var outDoc = converter.Convert(analysisResult, inDoc, outStr);
```
```java
// Create a stream for the output PDF/A file.
FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW);
// Convert the input document to the recommended conformance level using the converter object.
Document outDoc = converter.convert(analysisResult, inDoc, outStr);
```
## Checking the conversion results
If you plan to perform further processing, you may want to check the result of the conversion first.
The overall success can be read from the highest `EventSeverity` that has been collected by the event handler during the conversion:
```csharp
// Check if critical conversion events occurred
switch (eventsSeverity)
{
case EventSeverity.Information:
Console.WriteLine(\$"Successfully converted document to {outDoc.Conformance}.");
break;
case EventSeverity.Warning:
Console.WriteLine(\$"Warnings occurred during the conversion of document to {outDoc.Conformance}.");
Console.WriteLine(\$"Check the output file to decide if the result is acceptable.");
break;
case EventSeverity.Error:
throw new Exception(\$"Unable to convert document to {conformance} because of critical conversion events.");
}
```
```java
// Check if critical conversion events occurred
switch (el.getEventsSeverity())
{
case INFORMATION:
System.out.println("Successfully converted document to " + outDoc.getConformance() + ".");
break;
case WARNING:
System.out.println("Warnings occurred during the conversion of document to " + outDoc.getConformance() + ".");
System.out.println("Check the output file to decide if the result is acceptable.");
break;
case ERROR:
throw new Exception("Unable to convert document to " + conformance + " because of critical conversion events.");
}
```
Here's an example of the output that is generated by this sample code:
```
- Information: ManagedColors: Created calibrated color space substitute for DeviceRGB. (content of page 1)
Successfully converted document to PDF/A-2u.
```
### Full example
{/*sample source: PdfToolsSDK/Samples/Templates/validateconvert.cs*/}
```csharp
// Open input document
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);
// Create a Conformance object that specifies the PDF/A level against which the document is to be validated prior to conversion.
// Here, PDF/A-2b is specified.
var conformance = new Conformance(2, Conformance.PdfALevel.B);
// Create the Validator object, and use the Conformance object to create
// an AnalysisOptions object that controls the behavior of the Validator.
var validator = new Validator();
var analysisOptions = new AnalysisOptions() { Conformance = conformance };
// Run the analysis, and check the results.
// Only proceed if document is not conforming.
var analysisResult = validator.Analyze(inDoc, analysisOptions);
if (analysisResult.IsConversionRecommended) {
return; // No conversion is required.
}
// Create a converter object
var converter = new Converter();
// Add handler for conversion events
var eventsSeverity = EventSeverity.Information;
converter.ConversionEvent += (s, e) =>
{
// Get the event's suggested severity
var severity = e.Severity;
// Optionally, the suggested severity can be changed according to
// the requirements of your conversion process and, for example,
// the event's category (e.Category).
if (severity > eventsSeverity)
eventsSeverity = severity;
// Report conversion event
Console.WriteLine("- {0} {1}: {2} ({3}{4})",
severity.ToString()[0], e.Category, e.Message, e.Context, e.PageNo > 0 ? " page " + e.PageNo : ""
);
};
// Create stream for output file
using var outStr = File.Create(outPath);
// Convert the input document to PDF/A using the converter object
// and its conversion event handler
using var outDoc = converter.Convert(analysisResult, inDoc, outStr);
// Check if critical conversion events occurred
switch (eventsSeverity)
{
case EventSeverity.Information:
Console.WriteLine(\$"Successfully converted document to {outDoc.Conformance}.");
break;
case EventSeverity.Warning:
Console.WriteLine(\$"Warnings occurred during the conversion of document to {outDoc.Conformance}.");
Console.WriteLine(\$"Check the output file to decide if the result is acceptable.");
break;
case EventSeverity.Error:
throw new Exception(\$"Unable to convert document to {conformance} because of critical conversion events.");
}
```
{/*sample source: PdfToolsSDK/Samples/Templates/validateconvert.java*/}
```java
// Open input document
try (FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
Document inDoc = Document.open(inStr))
{
// Create a Conformance object that specifies the PDF/A level against which the document is to be validated prior to conversion.
// Here, PDF/A-2b is specified.
Conformance conformance = new Conformance(new Conformance.PdfAVersion(2, Conformance.PdfAVersion.Level.B));
// Create the Validator object, and use the Conformance object to create
// an AnalysisOptions object that controls the behavior of the Validator.
Validator validator = new Validator();
AnalysisOptions analysisOptions = new AnalysisOptions();
analysisOptions.setConformance(conformance);
// Run the analysis, and check the results.
// Only proceed if document is not conforming.
AnalysisResult analysisResult = validator.analyze(inDoc, analysisOptions);
if (analysisResult.getIsConversionRecommended())
{
return; // No conversion is required.
}
// Create output stream
try (FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW))
{
// Create a converter object
Converter converter = new Converter();
// Add handler for conversion events
class EventListener implements ConversionEventListener
{
private EventSeverity eventsSeverity = EventSeverity.INFORMATION;
public EventSeverity getEventsSeverity() {
return eventsSeverity;
}
@Override
public void conversionEvent(ConversionEvent event) {
// Get the event's suggested severity
EventSeverity severity = event.getSeverity();
// Optionally, the suggested severity can be changed according to
// the requirements of your conversion process and, for example,
// the event's category (e.Category).
if (severity.ordinal() > eventsSeverity.ordinal())
eventsSeverity = severity;
// Report conversion event
System.out.format("- %c %s: %s (%s%s)%n", severity.toString().charAt(0), event.getCategory(), event.getMessage(), event.getContext(), event.getPageNo() > 0 ? " on page " + event.getPageNo() : "");
}
}
EventListener el = new EventListener();
converter.addConversionEventListener(el);
// Convert the input document to PDF/A using the converter object
// and its conversion event handler
try (Document outDoc = converter.convert(analysisResult, inDoc, outStr))
{
// Check if critical conversion events occurred
switch (el.getEventsSeverity())
{
case INFORMATION:
System.out.println("Successfully converted document to " + outDoc.getConformance() + ".");
break;
case WARNING:
System.out.println("Warnings occurred during the conversion of document to " + outDoc.getConformance() + ".");
System.out.println("Check the output file to decide if the result is acceptable.");
break;
case ERROR:
throw new Exception("Unable to convert document to " + conformance + " because of critical conversion events.");
}
}
}
}
```
:::note Converting signed documents
If you convert a signed PDF to PDF/A, any signatures present in the document are removed before conversion. Therefore, if you need to include a signature in a PDF/A conformant document, first convert to PDF/A and then **[sign the document](../sign-and-secure/sign/sign-document.mdx)**.
:::
---
## Archive PDF document to TIFF image archive
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
Convert a PDF document into a TIFF image suitable for a specific purpose, such as archiving, digital viewing, or faxing.
You can adjust the conversion profile to suit the specific requirements of the document workflow.
:::tip Quick start with a code sample
Download the full sample now in **[C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=C)**, **[C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=CS)**, **[Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=Java)**, **[Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=Python)**, and **[Visual Basic](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=VB)**.
Interested in Go, Rust or other programming language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.
:::
:::info
For more information about PDF to image conversion profiles, see [Conversion profiles](../convert/conversion-profiles.mdx#pdf-to-image-conversion-profiles).
:::
**Steps to archive a document**
1. [Reading the input document](#reading-the-input-document)
2. [Selecting a conversion profile](#selecting-a-conversion-profile)
3. [Adjusting the conversion profile](#adjusting-the-conversion-profile)
4. [Converting the document to an image](#converting-the-document-to-an-image)
5. [Full example](#full-example)
---
:::note Before you begin
You need to **[initialize the library](/docs/licenses/products/pdf-tools-sdk-license/#activate-the-pdftools-sdk-license)**.
:::
## Reading the input document
First you need to read the PDF document you want to archive. To do this, load the input document from the file system into a (read-only) PDF `Document`.
This `Document` can then later be passed to the `Converter`.
```csharp
// Open image document
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);
```
```java
// Open input document
FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
com.pdftools.pdf.Document inDoc = com.pdftools.pdf.Document.open(inStr);
```
## Selecting a conversion profile
You start the conversion process by creating a conversion `Profile` object.
The `Profile` object defines the parameters that are applied to the conversion process.
This example uses the `Archive` profile, which is intended for document workflows that generate an output for archiving in TIFF image format.
```csharp
// Create a profile that defines the conversion parameters.
// The Archive profile converts PDF documents to TIFF images for archiving.
var profile = new Profiles.Archive();
```
```java
// Create the profile that defines the conversion parameters.
// The Archive profile converts PDF documents to TIFF images for archiving.
Archive profile = new Archive();
```
## Adjusting the conversion profile
The default conversion `Profile` settings are sufficient for most document workflows.
If the document workflow has specific requirements (for example, the use of a specific compression algorithm), you can adjust the properties of the conversion `Profile` directly.
For more information about PDF to image conversion profiles, see [Conversion profiles](../convert/conversion-profiles.mdx#pdf-to-image-conversion-profiles).
## Converting the document to an image
After creating the `Profile` object and adjusting for any workflow-specific properties, the final step is to instantiate a `Converter` object and call its `ConvertDocument` method.
The output image file is created at the specified path.
```csharp
// Create output stream
using var outStr = File.Create(outPath);
// Convert the PDF document to an image document
using var outDoc = new Converter().ConvertDocument(inDoc, outStr, profile);
```
```java
// Create output stream
FileStream outStream = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW);
// Convert the PDF document to an image document
com.pdftools.image.Document outDoc = new Converter().convertDocument(inDoc, outStream, profile))
```
## Full example
{/*sample source: PdfToolsSDK/Samples/Templates/pdf2imgsimple.cs*/}
```csharp
// Open input document
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);
// Create a profile that defines the initial conversion parameters.
// The Archive profile converts PDF documents to TIFF images for archiving.
var profile = new Profiles.Archive();
// Optionally, the profile's parameters can be changed according to the
// requirements of your conversion process.
// Create output stream
using var outStr = File.Create(outPath);
// Convert the PDF document to an image document
using var outDoc = new Converter().ConvertDocument(inDoc, outStr, profile);
```
{/*sample source: PdfToolsSDK/Samples/Templates/pdf2imgsimple.java*/}
```java
// Create the profile that defines the conversion parameters.
// The Archive profile converts PDF documents to TIFF images for archiving.
Archive profile = new Archive();
// Optionally, the profile's parameters can be changed according to the
// requirements of your conversion process.
try (
// Open input document
FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
com.pdftools.pdf.Document inDoc = com.pdftools.pdf.Document.open(inStr);
// Create output stream
FileStream outStream = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW);
// Convert the PDF document to an image document
com.pdftools.image.Document outDoc = new Converter().convertDocument(inDoc, outStream, profile))
{
}
```
---
## Merge and split PDF documents
The Pdftools SDK lets you assemble pages from one or more input PDF documents and images into any combination of output PDF documents and images.
It offers complete control over the generated documents by providing copying options that you can configure to your needs.
The Pdftools SDK features fast performance and efficient memory usage, making it ideal for processing large batches of documents and time-sensitive processes.
## Merge documents
Merge multiple PDF files and images into a single output PDF document using the `DocumentAssembler` class of the Pdftools SDK.
For example, convert a portfolio of documents and images a customer uploaded into a single output PDF document, suitable for further processing and archiving.
During this process, duplicated resources such as fonts are identified and merged, significantly reducing the size of the output PDF document. The `DocumentAssembler` class automatically resolves conflicts between named elements like form fields.
:::tip Get started
Learn to merge multiple PDF documents and images into one output PDF document on the **[Merge PDF documents](merge-pdfs.mdx)** page.
:::
## Split documents
Split a single PDF document into multiple output PDF documents and images using the `DocumentAssembler` class of the Pdftools SDK.
For example, you can split an input PDF document, in which every page represents an invoice for a different customer into multiple output PDF documents with one output document for each customer.
During this process, only the resources required by each page are copied to the output document containing that page, ensuring that PDF documents do not have redundant or potentially sensitive information.
:::tip Get started
Learn to split one input PDF document into multiple output PDF documents on the **[Split a PDF document](split-a-pdf.mdx)** page.
:::
## Merge and split combined
You can also split and re-merge multiple input documents into numerous output documents simultaneously, allowing you to efficiently assemble documents without the hassle of temporary files representing intermediate states of the process.
{/* TODO: It would be cool to one day add the Dossier functionality from the PDF Structure API here */}
---
## Merge PDF documents
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
The Pdftools SDK lets you assemble pages from multiple input PDF documents into a single output PDF document.
During this process, duplicated resources such as fonts are identified and merged, significantly reducing the size of the output PDF document.
The `DocumentAssembler` class automatically resolves conflicts between named elements like form fields.
:::tip Quick start with a code sample
Download the full sample now in **[C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Merge/Download?technology=C)**, **[C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Merge/Download?technology=CS)**, **[Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Merge/Download?technology=Java)**, **[Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Merge/Download?technology=Python)**, and **[Visual Basic](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Merge/Download?technology=VB)**.
Interested in Go, Rust or other programming language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.
:::
Depending on the requirements, you can adjust the characteristics of the output document by setting the PageCopyOptions Class used in the assembly process.
Depending on the requirements, you can adjust the characteristics of the output document by setting the Class PageCopyOptions used in the assembly process.
You can also add images to the output document by [converting an image to a PDF document](../convert/convert-image-pdf.mdx) and then merging the converted image into the output PDF document.
**Steps to merge PDF documents**:
1. [Creating a DocumentAssembler object](#creating-a-documentassembler-object)
2. [Reading the input documents](#reading-the-input-documents)
3. [Appending to the output document](#appending-to-the-output-document)
4. [Running the Assemble method](#running-the-assemble-method)
5. [Full example](#full-example)
---
:::note Before you begin
You need to **[initialize the library](/docs/licenses/products/pdf-tools-sdk-license/#activate-the-pdftools-sdk-license)**.
:::
## Creating a DocumentAssembler object
Create the `DocumentAssembler` object. This object will generate the output PDF document. Instantiate the `DocumentAssembler` and pass it an output `Stream` (for example, a file or memory stream) that will contain the output data.
```csharp
// Open an output stream and pass it to the DocumentAssembler
using var outStream = File.Create(outPath);
using var docAssembler = new PdfTools.DocumentAssembly.DocumentAssembler(outStream);
```
```java
// Open an output stream and pass it to the DocumentAssembler
FileStream outStream = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW);
DocumentAssembler docAssembler = new DocumentAssembler(outStream)) {
```
## Reading the input documents
Iterate through the input document set, loading each file as a `Document`.
```csharp
// Iterate through the set of input PDF documents
foreach (var inPath in inPaths)
{
using var inStream = File.OpenRead(inPath);
using var inDoc = PdfTools.Pdf.Document.Open(inStream);
```
```java
// Iterate through the set of input PDF documents
for (String inPath : inPaths) {
FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
Document inDoc = Document.open(inStr);
```
## Appending to the output document
Select a page range from the input `Document` by passing optional `firstPage` and `lastPage` parameters to the `Append` method of the `DocumentAssembler` object. If these parameters are not passed, the entire input `Document` is appended to the output PDF document.
This example uses the default parameters, so the entire input `Document` is appended.
```csharp
// Append the entire content of each input document to the output document
// Optionally, firstPage and lastPage parameters can be passed to append only a range of pages
docAssembler.Append(inDoc);
```
```java
// Append the entire content of each input document to the output document
// Optionally, firstPage and lastPage parameters can be passed to append only a range of pages
docAssembler.append(inDoc);
```
## Running the Assemble method
After using the `Append` method to merge the input documents into the output PDF document, the final step is to call the `Assemble` method. This method creates the structure of the output PDF document and writes the document to the output `Stream` of the `DocumentAssember` object.
```csharp
// Create the final structure of the output PDF document and write it to the output stream
docAssembler.Assemble();
```
:::tip
Don't forget that some objects (like the `Document` object) must be explicitly closed. For these objects, we recommend using the mechanism for [automatically closing objects](../../api-references/technical-notes/dotnet-notes/#idisposable-objects).
:::
```java
// Create the final structure of the output PDF document and write it to the output stream
docAssembler.assemble();
```
:::tip
Don't forget that some objects (like the `Document` object) must be explicitly closed. For these objects, we recommend using the mechanism for [automatically closing objects](../../api-references/technical-notes/java-notes/#autocloseable-objects).
:::
## Full example
{/*sample source: PdfToolsSDK/Samples/Templates/merge.cs*/}
```csharp
// Create output stream
using var outStream = File.Create(outPath);
using var docAssembler = new PdfTools.DocumentAssembly.DocumentAssembler(outStream);
// Iterate through the set of input PDF documents
foreach (var inPath in inPaths)
{
using var inStream = File.OpenRead(inPath);
using var inDoc = PdfTools.Pdf.Document.Open(inStream);
// Append the entire content of each input document to the output document
docAssembler.Append(inDoc);
}
// Create the final structure of the output PDF document and write it to the output stream
docAssembler.Assemble();
```
{/*sample source: PdfToolsSDK/Samples/Templates/merge.java*/}
```java
try (
// Create output stream
FileStream outStream = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW);
DocumentAssembler docAssembler = new DocumentAssembler(outStream)) {
// Iterate through the set of input PDF documents
for (String inPath : inPaths) {
try (
FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
Document inDoc = Document.open(inStr)) {
// Append the entire content of each input document to the output document
docAssembler.append(inDoc);
}
}
// Create the final structure of the output PDF document and write it to the output stream
docAssembler.assemble();
}
```
---
## Split PDF document
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
The Pdftools SDK lets you split a single input PDF document into multiple output PDF documents and images.
During this process, only the resources required by each page are copied to the output document containing that page.
This ensures your output PDF files do not contain redundant or potentially sensitive information.
:::tip Quick start with a code sample
Download the full sample now in **[C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Split/Download?technology=C)**, **[C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Split/Download?technology=CS)**, **[Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Split/Download?technology=Java)**, **[Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Split/Download?technology=Python)**, and **[Visual Basic](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Split/Download?technology=VB)**.
Interested in Go, Rust or other programming language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.
:::
Depending on the requirements, you can adjust the characteristics of the output document by setting the PageCopyOptions Class used in the assembly process.
Depending on the requirements, you can adjust the characteristics of the output document by setting the Class PageCopyOptions used in the assembly process.
You can also generate the output documents as images by [converting a PDF document to an image](../convert/convert-pdf-image.mdx).
**Steps to split PDF documents**:
1. [Opening the input Document](#opening-the-input-document)
2. [Creating the DocumentAssembler object](#creating-the-documentassembler-object)
3. [Appending to the output document](#appending-to-the-output-document)
4. [Running the Assemble method](#running-the-assemble-method)
5. [Full example](#full-example)
---
:::note Before you begin
You need to **[initialize the library](/docs/licenses/products/pdf-tools-sdk-license/#activate-the-pdftools-sdk-license)**.
:::
## Opening the input Document
Read the PDF document you want to convert. To do this, load the input document from the file system into a (read-only) PDF `Document`.
```csharp
// Open input document
using var inStream = File.OpenRead(inPath);
using var inDoc = PdfTools.Pdf.Document.Open(inStream);
```
```java
// Open input document
FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
Document inDoc = Document.open(inStr)) {
```
## Creating the DocumentAssembler object
Create the `DocumentAssembler` object that will generate the output PDF document. To do this, instantiate the `DocumentAssembler` and pass it an output `Stream` (for example, a file or memory stream) that will contain the output data.
The following example creates one output PDF document for each input document page.
```csharp
// Repeat for each page in the input document
for (int i = 1; i <= inDoc.PageCount; ++i)
{
// Create the output stream and pass it to the document assembler
using var outStream = File.Create(outPathPrefix + i + ".pdf");
using var docAssembler = new PdfTools.DocumentAssembly.DocumentAssembler(outStream);
```
```java
// Repeat for each page in the input document
for (int i = 1; i <= inDoc.getPageCount(); ++i) {
// Create the output stream and pass it to the document assembler
FileStream outStream = new FileStream(outPathPrefix + i + ".pdf", FileStream.Mode.READ_WRITE_NEW);
DocumentAssembler docAssembler = new DocumentAssembler(outStream);
```
## Appending to the output document
You can select a page range to copy from the input `Document` by passing `firstPage` and `lastPage` parameters to the `Append` method of the `DocumentAssembler` object.
In this example, we only append the current page of the input PDF document to each output document.
```csharp
// Append the current page of the input PDF document to a single-page output document
docAssembler.Append(inDoc, i, i);
```
```java
// Append the current page of the input PDF document to a single-page output document
docAssembler.append(inDoc, i, i);
```
## Running the Assemble method
After using the `Append` method to add the required pages to the output PDF document, the final step is to call the `Assemble` method. This method creates the structure of the output PDF document and writes the document to the output `Stream` of the `DocumentAssember` object.
```csharp
// Create the final structure of the output PDF document and write it to the output stream
docAssembler.Assemble();
```
:::tip
Don't forget that some objects (like the `Document` object) must be explicitly closed. For these objects, we recommend using the mechanism for [automatically closing objects](../../api-references/technical-notes/dotnet-notes/#idisposable-objects).
:::
```java
// Create the final structure of the output PDF document and write it to the output stream
docAssembler.assemble();
```
:::tip
Don't forget that some objects (like the `Document` object) must be explicitly closed. For these objects, we recommend using the mechanism for [automatically closing objects](../../api-references/technical-notes/java-notes/#autocloseable-objects).
:::
## Full example
{/*sample source: PdfToolsSDK/Samples/Templates/split.cs*/}
```csharp
// Open input document
using var inStream = File.OpenRead(inPath);
using var inDoc = PdfTools.Pdf.Document.Open(inStream);
// Repeat for each page in the input document
for (int i = 1; i <= inDoc.PageCount; ++i)
{
// Create the output stream and pass it to the document assembler
using var outStream = File.Create(outPathPrefix + i + ".pdf");
using var docAssembler = new PdfTools.DocumentAssembly.DocumentAssembler(outStream);
// Append the current page of the input PDF document to the output document
docAssembler.Append(inDoc, i, i);
// Create the final structure of the output PDF document and write it to the output stream
docAssembler.Assemble();
}
```
{/*sample source: PdfToolsSDK/Samples/Templates/split.java*/}
```java
try (
// Open input document
FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
Document inDoc = Document.open(inStr)) {
for (int i = 1; i <= inDoc.getPageCount(); ++i) {
try (
// Create output stream for each page of the input document
FileStream outStream = new FileStream(outPathPrefix + i + ".pdf", FileStream.Mode.READ_WRITE_NEW);
DocumentAssembler docAssembler = new DocumentAssembler(outStream)) {
docAssembler.append(inDoc, i, i);
docAssembler.assemble();
}
}
}
```
---
## Code samples(Code-samples)
import DocCardList from '@theme/DocCardList';
Start using the Pdftools SDK and Toolbox add-on libraries with code samples. Integrate advanced PDF manipulation, optimization, and validation, as well as low-level access to the content of PDF files into your application in Java, .NET, C, and Python.
Start using the Pdftools SDK library with code samples. Integrate advanced PDF manipulation, optimization, and validation tasks into your application in Java, .NET, C, and Python.
:::info
Select a code sample in a specific language and download it. The code samples illustrate how to integrate the SDK into your projects for specific use cases. Each code sample includes a README file that gives instructions on how to run the code sample to process one or multiple files.
:::
:::tip
Do you miss a specific sample and want us to include it here? Let us know through the [Contact page](https://www.pdf-tools.com/contact/), and we'll add it to our sample backlog.
:::
---
## Toolbox add-on code samples
import { CodeSamplesWithTOC, CodeSamples } from '@site/src/components/CodeSamples/CodeSamplesWithTOC'
Start using the Toolbox add-on library with code samples. Integrate low-level access to the content of PDF files into your application in Java, .NET, and C.
:::info
Select a code sample in a specific language and download it. The code samples illustrate how to integrate the SDK into your projects for specific use cases. Each code sample includes a README file that gives instructions on how to run the code sample to process one or multiple files.
:::
:::tip
Do you miss a specific sample and want us to include it here? Let us know through the [Contact page](https://www.pdf-tools.com/contact/), and we'll add it to our sample backlog.
:::
---
## Convert with the Pdftools SDK
With the Pdftools SDK you can convert various file formats:
- [Convert images to PDF](#convert-images-to-pdf)
- [Convert a PDF document to image](#convert-pdfs-to-images)
---
## Convert PDFs to images
Create single-page and multi-page image files and rasterized PDF documents from PDF documents.
Specify how PDFs are converted to images, choosing the resolution, quality in lossy image compression, as well as the color space and depth to be used.
Convert PDFs to TIFF-F suitable for fax transmission using the [Fax conversion profile](conversion-profiles.mdx#fax).
:::note Accepted formats
| Input | Output |
| ------------------------------------------- | --------------- |
| PDF 1.x, PDF 2.0, PDF/A-1, PDF/A-2, PDF/A-3 | TIFF, PNG, JPEG |
:::
**Image processing**
- Set resolution (DPI)
- Set TIFF file compression algorithm
- Set the quality of lossy image compression
**Color management**
- Set background color
- Set color space
**Page layout**
- Define page dimensions in standard page sizes, points or pixels
- Set rotation: force portrait or landscape or inherit rotation from original document
:::tip Get started
Learn how to **[convert a PDF document to an image](convert-pdf-image.mdx)**.
:::
---
## Convert images to PDF
Convert one or more single-page or multi-page raster images into an output PDF document. Use default [image to PDF conversion profiles](conversion-profiles.mdx#image-to-pdf-conversion-profiles) to automatically process image conversion.
Specify how the images are processed, selecting compression level, image quality, and resolution.
Choose the formatting of the output document, including page size, area, scaling, and image position and orientation.
Determine the conformance level of the output PDF document, and set additional document settings such as attributes, permissions, alternative text.
:::note Accepted formats
| Input | Output |
| -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| BMP, GIF, JBIG2, JPEG, JPEG2000, JPEG-LS, PBM, PNG, TIFF, LZW, CCITT | PDF 1.x, PDF 2.0, PDF/A-1, PF/A-1b, PDF/A-2, PDF/A-2b, PDF/A-2u, PDF/A-3, PDF/A-3b, PDF/A-3u |
:::
**Image processing**
- Select image compression, depending on the image type
- Select image quality for lossy compression
- Set standard resolution (DPI / X and Y coordinates)
- Choose optional JPEG image recompression
- Support for image masks and mixed raster content (MRC)
**Page layout**
- Select PDF page size or determine automatically
- Select page area
- Set scaling
- Set image position
- Set image orientation (portrait or landscape)
**PDF document settings**
- Set encryption and user access permissions
- Set document attributes
- Select and embed ICC color profiles
- Embed XMP metadata
:::tip Get started
Learn how to **[convert an image to a PDF document](convert-image-pdf.mdx)**.
:::
---
---
## Conversion profiles
Conversion profiles define how an input file is converted and rendered in an output file.
A profile contains a set of conversion parameters that are combined for a practical use case. For example, creating documents for viewing, archiving, or sending via fax.
Although a conversion profile provides default parameters for a specific use case, most of the parameters of a conversion profile can be adjusted to suit the specific requirements of a document workflow.
The Pdftools SDK provides two types of conversion profile:
- **[PDF to image conversion profiles](#pdf-to-image-conversion-profiles)**: used when converting PDF documents to images.
- **[Image to PDF conversion profiles](#image-to-pdf-conversion-profiles)**: used when converting images to PDF documents.
---
## PDF to image conversion profiles
PDF to image conversion profiles provide a set of default parameters that are used when coverting PDF documents to images.
The Pdftools SDK provides three image conversion profiles:
- [Viewing](#viewing)
- [Archive](#archive)
- [Fax](#fax)
### Viewing
The `Viewing` profile is used to convert PDFs to rasterized JPEG or PNG images for use in web and desktop viewing applications, or for use as thumbnails.
For JPEG and PNG images, the default output uses the RGB color space, has a resolution of 150 DPI, and is rendered on a white background.
For PNG images, a lossless compression algorithm is applied.
For JPEG images, JPEG compression is applied with a default quality factor of 85.
The following options may also be used:
- **Quality factor (JPEG)**: 0 - 100
- **Color space (JPEG)**: RGB, CMYK or gray
- **Color space (PNG)**: RGB or gray
- **Background**: Transparent or white
- **Resolution**: DPI (0.0 - 10,000.0) or as a maximum image size (in pixels)
### Archive
The `Archive` profile is used to convert PDF documents to TIFF images for archiving as rasterized images.
By default, the output image inherits the color space of the PDF document, has a resolution of 300 DPI, and uses the LZW compression algorithm.
The following options may also be used:
- **Compression algorithm**: LZW, JPEG or flate
- **Color space**: inherit the color space of the PDF document, RGB, CMYK or gray
- **Resolution**: 0.0 - 10,000.0 DPI
### Fax
The `Fax` profile is designed for converting PDFs into TIFF-F conforming rasterized images for fax transmission.
The output format is a multi-page TIFF file, which contains all PDF pages converted into rasterized images.
By default, the output images are scaled to a width of 1728 pixels, with a horizontal resolution of 204 DPI, and a vertical resolution of 98 DPI.
All colors and grayscale tones are converted to bitonal by applying dithering.
The output image is compressed using the CCITT Group 3 compression algorithm.
The following options may also be used:
- **Compression algorithm**: CCITT Group 3 or CCITT Group 4
- **Vertical resolution**: 98 DPI (Standard) or 196 DPI (High)
---
## Image to PDF conversion profiles
Image to PDF conversion profiles provide a set of default parameters that are used when coverting images to PDF documents.
The Pdftools SDK provides two image conversion profiles:
- [Default](#default)
- [Archive](#archive-1)
### Default
The `Default` profile is used for document workflows that need to convert images to PDF documents, but do not have long-term archiving or accessibility requirements.
By default, the images are placed onto A4-sized (210 mm x 297 mm) pages in portrait orientation with 20 mm (0.79 in) margins.
Large images are scaled down to fit the page.
The PDF conformance level is set to [PDF 1.7](/docs/knowledge/pdf-standards#pdf-17-iso-32000-1).
The following options may also be used:
- **Scaling options**: Import all images in portrait orientation, automatically detect scaling based on image dimensions, or automatically detect scaling based on image type
- **Page dimensions**: standard (A3, A4, A5, Letter, Legal) or custom page sizes, in portrait or landscape orientation
- **Page margins**: Standard or custom page margins
- **PDF conformance**: PDF 1.x or [PDF 2.0](/docs/knowledge/pdf-standards#pdf-20-iso-32000-2)
### Archive
The `Archive` profile is designed for document workflows that need to convert images to PDF documents, and comply with long-term archiving or document accessibility requirements.
By default, the output of the `Archive` profile matches the output of the `Default` profile, except that the default PDF conformance level for the `Archive` profile is set to [PDF/A-2b](/docs/knowledge/pdf-a/#pdfa-2).
The same options apply to the `Archive` profile as to the `Default` profile. However, the following additional options are available:
- **PDF conformance**: PDF/A-1b, PDF/A-1a, PDF/A-2b, PDF/A-2u, PDF/A-2a, PDF/A-3b, PDF/A-3u, or PDF/A-3a
- **Accessible content**: Provide language and alternate text for each imported image (required for level A conformance)
:::tip
For PDF/A-1a, PDF/A-2a, and PDF/A-3a conformance, accessible content must be provided.
For more information about creating accessible PDF documents, see **[Convert image to Accessible PDF](../archive/archive-image-pdfa-accessible.mdx)**.
:::
---
## Convert an image to a PDF document
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
Convert one or more TIFF, JPEG, BMP, GIF, PNG, JBIG2, or JPEG2000 images into an output PDF document.
Content for long-term archiving and document accessibility can be added during the conversion process.
The formatting and conformance level of the output PDF document can be adjusted to suit the requirements of the document workflow.
:::tip Quick start with a code sample
Download the full sample now in **[C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Img2PdfDefault/Download?technology=C)**, **[C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Img2PdfDefault/Download?technology=CS)**, **[Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Img2PdfDefault/Download?technology=Java)**, **[Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Img2PdfDefault/Download?technology=Python)**, and **[Visual Basic](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Img2PdfDefault/Download?technology=VB)**.
Interested in Go, Rust or other programming language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.
:::
**Steps to convert a document**
1. [Reading the input image](#reading-the-input-image)
2. [Selecting a conversion profile](#selecting-a-conversion-profile)
3. [Adjusting the conversion profile](#adjusting-the-conversion-profile)
4. [Converting the image to a PDF document](#converting-the-image-to-a-pdf-document)
5. [Full example](#full-example)
---
:::note Before you begin
You need to **[initialize the library](/docs/licenses/products/pdf-tools-sdk-license/#activate-the-pdftools-sdk-license)**.
:::
## Reading the input image
First you need to read the image you want to convert. To do this, load the input image from the file system into a read-only image `Document`.
This `Document` can then later be passed to the `Converter`.
```csharp
// Open image document
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);
```
```java
// Open input document
FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
com.pdftools.image.Document inDoc = com.pdftools.image.Document.open(inStr);
```
## Selecting a conversion profile
You start the image conversion process by creating a conversion `Profile` object to determine the [conversion profile](conversion-profiles.mdx).
The `Profile` object defines the parameters that are applied to the conversion process.
:::tip
For more information about image to PDF conversion profiles, see [Conversion profiles](conversion-profiles.mdx#image-to-pdf-conversion-profiles).
:::
This example uses the `Default` profile, which is designed for document workflows that need to convert images to PDF documents, but do not have long-term archiving or accessibility requirements.
```csharp
// Create the profile that defines the conversion parameters.
// The Default profile converts images to PDF documents.
var profile = new Profiles.Default();
```
```java
// Create the profile that defines the conversion parameters.
// The Default profile converts images to PDF documents.
Default profile = new Default();
```
## Adjusting the conversion profile
If the images must be added to the PDF document in a specific way (for example, if the image size should be preserved or a specific page orientation should be used), this can be achieved by changing the properties of the conversion profile.
The PDF conformance level may also be adjusted in this way.
For more information about image to PDF conversion profiles, see [Conversion profiles](conversion-profiles.mdx#image-to-pdf-conversion-profiles).
## Converting the image to a PDF document
After creating the `Profile` object and adjusting for any workflow-specific properties, the final step is to instantiate a `Converter` object and call its `Convert` method.
The output PDF document is created at the specified path.
```csharp
// Create output stream
using var outStr = File.Create(outPath);
// Convert the image to a PDF document
using var outDoc = new Converter().Convert(inDoc, outStr, profile);
```
```java
// Create output stream
FileStream outStream = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW);
// Convert the image to a PDF document
Document outDoc = new Converter().convert(inDoc, outStream, profile));
```
## Full example
{/*sample source: PdfToolsSDK/Samples/Templates/img2pdfdefault.cs*/}
```csharp
// Open image document
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);
// Create the profile that defines the conversion parameters.
// The Default profile converts images to PDF documents.
var profile = new Profiles.Default();
// Optionally, the profile's parameters can be changed according to the
// requirements of your conversion process.
// Create output stream
using var outStr = File.Create(outPath);
// Convert the image to a PDF document
using var outDoc = new Converter().Convert(inDoc, outStr, profile);
```
{/*sample source: PdfToolsSDK/Samples/Templates/img2pdfdefault.java*/}
```java
// Create the profile that defines the conversion parameters.
// The Default profile converts images to PDF documents.
Default profile = new Default();
// Optionally, the profile's parameters can be changed according to the
// requirements of your conversion process.
try (
// Open input document
FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
com.pdftools.image.Document inDoc = com.pdftools.image.Document.open(inStr);
// Create output stream
FileStream outStream = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW);
// Convert the image to a PDF document
com.pdftools.pdf.Document outDoc = new Converter().convert(inDoc, outStream, profile))
{
}
```
---
## Convert a PDF document to an image
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
Convert a PDF document into an output image suitable for a specific purpose, such as archiving, digital viewing, or faxing.
The conversion profile can be adjusted to suit the specific requirements of the document workflow.
:::tip Quick start with a code sample
Download the full sample now in **[C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=C)**, **[C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=CS)**, **[Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=Java)**, **[Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=Python)**, and **[Visual Basic](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Split/Download?technology=VB)**.
Interested in Go, Rust or other programming language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.
:::
:::info
For more information about PDF to image conversion profiles, see [Conversion profiles](conversion-profiles.mdx#pdf-to-image-conversion-profiles).
:::
**Steps to convert a document**
1. [Reading the input document](#reading-the-input-document)
2. [Selecting a conversion profile](#selecting-a-conversion-profile)
3. [Adjusting the conversion profile](#adjusting-the-conversion-profile)
4. [Converting the document to an image](#converting-the-document-to-an-image)
5. [Full example](#full-example)
---
:::note Before you begin
You need to **[initialize the library](/docs/licenses/products/pdf-tools-sdk-license/#activate-the-pdftools-sdk-license)**.
:::
## Reading the input document
First you need to read the PDF document you want to convert. To do this, load the input document from the file system into a (read-only) PDF `Document`.
This `Document` can then later be passed to the `Converter`.
```csharp
// Open image document
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);
```
```java
// Open input document
FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
com.pdftools.pdf.Document inDoc = com.pdftools.pdf.Document.open(inStr);
```
## Selecting a conversion profile
You start the conversion process by creating a conversion `Profile` object.
The `Profile` object defines the parameters that are applied to the conversion process.
This example uses the `Archive` profile, which is intended for document workflows that generate an output for archiving in TIFF image format.
```csharp
// Create a profile that defines the conversion parameters.
// The Archive profile converts PDF documents to TIFF images for archiving.
var profile = new Profiles.Archive();
```
```java
// Create the profile that defines the conversion parameters.
// The Archive profile converts PDF documents to TIFF images for archiving.
Archive profile = new Archive();
```
## Adjusting the conversion profile
The default conversion `Profile` settings are sufficient for most document workflows.
If the document workflow has specific requirements (for example, the use of a specific compression algorithm), you can adjust the properties of the conversion `Profile` directly.
For more information about PDF to image conversion profiles, see [Conversion profiles](conversion-profiles.mdx#pdf-to-image-conversion-profiles).
## Converting the document to an image
After creating the `Profile` object and adjusting for any workflow-specific properties, the final step is to instantiate a `Converter` object and call its `ConvertDocument` method.
The output image file is created at the specified path.
```csharp
// Create output stream
using var outStr = File.Create(outPath);
// Convert the PDF document to an image document
using var outDoc = new Converter().ConvertDocument(inDoc, outStr, profile);
```
```java
// Create output stream
FileStream outStream = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW);
// Convert the PDF document to an image document
com.pdftools.image.Document outDoc = new Converter().convertDocument(inDoc, outStream, profile))
```
## Full example
{/*sample source: PdfToolsSDK/Samples/Templates/pdf2imgsimple.cs*/}
```csharp
// Open input document
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);
// Create a profile that defines the initial conversion parameters.
// The Archive profile converts PDF documents to TIFF images for archiving.
var profile = new Profiles.Archive();
// Optionally, the profile's parameters can be changed according to the
// requirements of your conversion process.
// Create output stream
using var outStr = File.Create(outPath);
// Convert the PDF document to an image document
using var outDoc = new Converter().ConvertDocument(inDoc, outStr, profile);
```
{/*sample source: PdfToolsSDK/Samples/Templates/pdf2imgsimple.java*/}
```java
// Create the profile that defines the conversion parameters.
// The Archive profile converts PDF documents to TIFF images for archiving.
Archive profile = new Archive();
// Optionally, the profile's parameters can be changed according to the
// requirements of your conversion process.
try (
// Open input document
FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
com.pdftools.pdf.Document inDoc = com.pdftools.pdf.Document.open(inStr);
// Create output stream
FileStream outStream = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW);
// Convert the PDF document to an image document
com.pdftools.image.Document outDoc = new Converter().convertDocument(inDoc, outStream, profile))
{
}
```
---
## Embed e-invoice
Learn how to embed e-invoices such as ZUGFeRD or Factur-X into PDF files using the Pdftools SDK, ensuring compliance with international e-invoicing standards. This guide outlines the key features and requirements for integrating e-invoices using the SDK.
## What are ZUGFeRD and Factur-X?
ZUGFeRD and Factur-X are hybrid e-invoicing standards that combine human-readable PDF/A-3 documents with embedded XML data for automated processing. Originally developed in Germany, ZUGFeRD was later aligned with the French Factur-X standard as part of the Franco-German digital agenda. Both standards conform to the European norm EN 16931, making them suitable for cross-border invoicing within the European Union.
Why use ZUGFeRD and Factur-X? For more details about why to use the e-invoice formats presented in this guide, review [ZUGFeRD - A standard for electronic invoices in PDF/A format](https://www.pdf-tools.com/pdf-knowledge/zugferd-standard-electronic-invoices/).
:::tip Quick start with a code sample
Download the full sample now in **[C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Zugferd/Download?technology=C)**, **[C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Zugferd/Download?technology=CS)**, **[Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Zugferd/Download?technology=Java)**, **[Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Zugferd/Download?technology=Python)**, and **[Visual Basic](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Zugferd/Download?technology=VB)**.
Interested in Go, Rust or other programming language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.
:::
## PDF/A-3 Compliance and invoice embedding
ZUGFeRD and Factur-X invoices require embedding structured XML data within a PDF/A-3 document. The PdfTools SDK integrates this process into its PDF-to-PDF/A conversion interface, ensuring the final document meets the necessary compliance requirements. As a result, invoices can only be embedded as part of a PDF/A-3 conversion. For information on converting any PDF into a PDF/A, review the [Archive a PDF document to PDF/A](../archive/archive-pdf-pdfa.mdx).
## Supported invoice formats and profiles
The PdfTools SDK supports multiple versions and profiles of ZUGFeRD and Factur-X, including:
- **ZUGFeRD 1.0**: Basic, Comfort, Extended
- **ZUGFeRD 2.0** or **2.1**: Minimum, Basic WL, Basic, EN 16931, Extended, XRechnung
- **Factur-X 1.0**: Minimum, Basic WL, Basic, EN 16931, Extended
The Pdftools SDK automatically detects the invoice type and version, ensuring seamless integration into the PDF without requiring manual specification.
## XML invoice handling
The SDK does not perform full validation of the invoice XML. Instead, it extracts key data elements necessary for correct integration into the PDF. The user's responsibility is to ensure the validity and correctness of the invoice XML. The SDK verifies specific fields to determine the invoice type and version but does not enforce full schema validation.
---
## Getting started with the Pdftools SDK
import DocCardList from '@theme/DocCardList';
Get up and running with the Pdftools SDK, the Toolbox add-on, and the Pdftools SDK Shell Tool.
Find an integration guide in your language or framework by clicking one of the following cards:
```
C:\Program Files\PDF Tools AG\
```
Included subdirectories are:
| Subdirectory | Description |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `~` | Contains important information in the `README.md` file. |
| `lib` | Runtime executable binaries and runtime import libraries: win-x86\PdfToolsSdk.dll and win-x86\PdfToolsSdk.lib for 32-bit Windows.win-x64\PdfToolsSdk.dll and win-x64\PdfToolsSdk.lib for 64-bit Windows.win-arm64\PdfToolsSdk.dll and win-arm64\PdfToolsSdk.lib for 64-bit Windows ARM. |
| `include` | Header files to add to your C or C++ project. The main header `PdfTools.h` includes all the other headers. |
```
/opt/pdftools.com/
```
Included subdirectories are:
| Subdirectory | Description |
| ------------ | ------------------------------------------------------------------------------------------------------------------------ |
| `~` | Contains important information in the `README.md` file. |
| `lib` | Runtime executable binaries for all supported platforms: linux-x64/libPdfToolsSdk.so for 64-bit Linuxlinux-arm64/libPdfToolsSdk.so for 64-bit Linux ARM |
| `include` | Header files to add to your C or C++ project. The main header `PdfTools.h` includes all the other headers. |
```
/opt/pdftools.com/
```
Included subdirectories are:
| Subdirectory | Description |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `~` | Contains important information in the `README.md` file. |
| `lib` | Runtime executable binaries: `osx-x64/libPdfToolsSdk.dylib` for 64-bit (Intel) macOS `osx-arm64/libPdfToolsSdk.dylib` for ARM (Apple Silicon) macOS |
| `include` | Header files to add to your C or C++ project. The main header `PdfTools.h` includes all the other headers. |
1. Optional: The native libraries must be available in your compiler's library path. This step is only required if your build process doesn't resolve it automatically:
Add the `lib\win-x64`, `lib\win-arm64` or `lib\win-x86` subdirectory to the `%PATH%` environment variable.
Create a link to the shared library from one of the standard library directories, e.g:
```
ln -s /opt/pdf-tools.com/lib/linux-x64/libPdfToolsSdk.so /usr/lib
```
Create a link to the shared library from one of the standard library directories. For example (for an Intel processor Mac):
```
ln -s /opt/pdf-tools.com/lib/osx-x64/libPdfToolsSdk.dylib /usr/lib
```
### Optional: Initialize the SDK
Learn how to remove watermarked output of the Pdftools SDK using a valid license key.
:::tip
You can try the Pdftools SDK without a license key for free. This section is **optional** if you want to evaluate this SDK. Initialization only lets you remove watermarks added to output files.
:::
:::info Getting a license key
Contact the Pdftools sales team through the [Contact page](https://www.pdf-tools.com/contact/) to get a full license. For additional information, review [Pdftools SDK license management](/docs/licenses/products/pdf-tools-sdk-license/).
:::
To remove watermarks, follow these steps:
1. Locate your license key. For more information, review [Find the license key](/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key).
1. Before you call any function of the Pdftools SDK, first call the `PdfTools_Sdk_Initialize` function.
```c
GOTO_CLEANUP_IF_FALSE_PRINT_ERROR(PdfTools_Sdk_Initialize(_T("insert-license-key-here"), NULL),
_T("Failed to set the license key. %s (ErrorCode: 0x%08x).\n"), szErrorBuff,
PdfTools_GetLastError());
```
Replace the `insert-license-key-here` with the value of your license key. Include the less-than (`<`) and greater-than (`>`) signs.
To get a code sample with the `PdfTools_Sdk_Initialize` function that you can use as a reference for your code, follow these steps:
1. On the [Code samples](../../code-samples/pdftools-sdk-samples.mdx) page, download and unzip a C code sample. For example: Download **[Convert PDF to image](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=C)** sample.
1. Unzip the file, and then find the `PdfTools_Sdk_Initialize` function in the main C file of the sample. For example: [Convert PDF to image](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=C) sample includes `PdfTools_Sdk_Initialize` function in the `pdftoolspdf2imgsimple.c` file.
1. Uncomment the function and replace `insert-license-key-here` with your license key.
### Uninitialize the SDK
After processing files with the Pdftools SDK, call the `Uninitialize` function to unload the library correctly:
```c
// Uninitialize library
PdfTools_Uninitialize();
```
### Implement your use case
- Find more use cases and sample projects on the [Code samples](../../code-samples/pdftools-sdk-samples.mdx) page.
- For more technical information about the Pdftools SDK for C, consult the [C technical notes](../../api-references/technical-notes/c-notes.mdx).
- If you need to configure a proxy, review [Configure proxy](/docs/licenses/products/pdf-tools-sdk-license/#configure-proxy) documentation section.
---
## Get started with .NET
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
This guide walks you through the steps to use a sample project, and then explains how to integrate the Pdftools SDK into your application with .NET.
:::tip
Try the Pdftools SDK without a license key for free.
:::
## Prerequisites
The Pdftools SDK for .NET requires **.NET and .NET Core 2.0 or higher**, or **.NET Framework 4.6.1 or higher**.
## Getting started with a sample project
Learn how to use the Pdftools SDK using a C# sample project and convert a PDF file to an image.
### Compile and run the sample
Switch between the following tabs to display steps for the command line interface or for the Visual Studio. To compile and run the sample, follow these steps:
1. Download a **[sample project](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=CS)**, and then unzip the file.
1. In the command line, navigate to the root directory of the unzipped sample project.
1. To render the sample PDF file `PdfPrimerWhitePaper.pdf` to a multi-page TIFF image format, run the following command:
```shell
dotnet run --framework net6.0 --project PdfToolsPdf2ImgSimple.csproj PdfPrimerWhitepaper.pdf tiff_output.tiff
```
The code sample takes:
- The input and output files are represented as a file name or a file path with the file name.
- Both file paths (input and output) can be relative or absolute.
Review the following snippet with a placeholder and compare it to the last step of the previous procedure:
```shell
dotnet run --framework net6.0 --project PdfToolsPdf2ImgSimple.csproj INPUT_FILE OUTPUT_FILE
```
:::info
This documentation uses Visual Studio 2022.
:::
1. Download a **[sample project](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=CS)**, and then unzip the file.
1. In the sample folder, double click `PdfToolsPdf2ImgSimple.csproj`
1. Click **Build** -> **Build Solution** to compile the project.
1. Within the sample project, open your terminal.
1. The sample project contains a PDF file `PdfPrimerWhitePaper.pdf`. To render it in multi-page TIFF image format, run:
```
./bin/Debug/net6.0/PdfToolsPdf2ImgSimple PdfPrimerWhitepaper.pdf tiff_output.tiff
```
The code sample takes:
- The input and output files are represented as a file name or a file path with the file name.
- Both file paths (input and output) can be relative or absolute.
Review the following snippet with a placeholder and compare it to the last step of the previous procedure:
```shell
./bin/Debug/net6.0/PdfToolsPdf2ImgSimple INPUT_FILE OUTPUT_FILE
```
:::tip
You can apply a similar procedure described in this tutorial for other code samples. For more information, see [Code samples](../../code-samples/pdftools-sdk-samples.mdx) page.
:::
## Integrate the SDK into your application
Integrate and initialize the Pdftools SDK into your application by following the instructions in the following sections.
### Add the SDK to your project
In the project directory, run the following command:
```shell
dotnet add package PdfTools
```
Optional: If you want to use a specific version of the Pdftools SDK, run the following command:
```shell
dotnet add package PdfTools --version VERSION_NUMBER
```
Replace the `VERSION_NUMBER` with a specific version of the Pdftools SDK you want to add to your project.
:::info
This documentation uses Visual Studio 2022 on Windows.
:::
1. Open your solution in Visual Studio.
1. Click **Tools** > **Nuget Package Manager** > **Manage NuGet Packages for Solution...**.
1. Click the **Search** tab and search for `Pdftools SDK`.
1. Select the NuGet package named `PdfTools by PDF Tools AG`, select your Project, and then click **Install**.
1. Click **OK** to allow the changes, and then review and **Accept** the license agreement.
### Optional: Initialize the SDK
Learn how to remove watermarked output of the Pdftools SDK using a valid license key.
:::tip
You can try the Pdftools SDK without a license key for free. This section is **optional** if you want to evaluate this SDK. Initialization only lets you remove watermarks added to output files.
:::
:::info Getting a license key
Contact the Pdftools sales team through the [Contact page](https://www.pdf-tools.com/contact/) to get a full license. For additional information, review [Pdftools SDK license management](/docs/licenses/products/pdf-tools-sdk-license/).
:::
To remove watermarks, follow these steps:
1. Locate your license key. For more information, review [Find the license key](/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key).
1. Before you call any function of the Pdftools SDK, first call the `Sdk.initialize` method.
```csharp
Sdk.Initialize("insert-license-key-here");
```
Replace the `insert-license-key-here` with the value of your license key. Include the less-than (`<`) and greater-than (`>`) signs.
:::info Try it without license key
You can try the Pdftools SDK without a license with watermarked results. For more information, review [Pdftools SDK license management](/docs/licenses/products/pdf-tools-sdk-license/). Without a valid license key the output files are watermarked. Get in touch with the Pdftools sales team through the [Contact page](https://www.pdf-tools.com/contact/) to get a full license.
:::
To get a working code sample with the `Sdk.initialize` method that you can use as a reference for your code, follow these steps:
1. On the [Code samples](../../code-samples/pdftools-sdk-samples.mdx) page, download and unzip a C# code sample. For example: Download **[Convert PDF to image](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=CS)** sample.
1. Unzip the file, and then find the `Sdk.initialize` method in the C# file of the sample. For example: [Convert PDF to image](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=CS) includes the `SDK.initialize` method in the `Program.cs` file.
1. Uncomment the method and replace the `insert-license-key-here` with your license key.
### Implement your use case
- Find more use cases and sample projects on the [Code samples](../../code-samples/pdftools-sdk-samples.mdx) page.
- For more technical information about the Pdftools SDK for .NET, consult the [.NET technical notes](../../api-references/technical-notes/dotnet-notes.mdx).
- If you need to configure a proxy, review [Configure proxy](/docs/licenses/products/pdf-tools-sdk-license/#configure-proxy) documentation section.
---
## Get started with Java
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
This guide walks you through the steps to use a sample project, and then explains how to integrate the Pdftools SDK into your application with the Java programming language.
:::tip
Try the Pdftools SDK without a license key for free.
:::
## Prerequisites
The Pdftools SDK for Java requires **Java version 8 or higher**.
## Getting started with a sample project
Learn how to use the Pdftools SDK using a Java sample project and convert a PDF file to an image.
### Compile and run the sample
Switch between the following tabs to display steps for the command line interface or for the Eclipse IDE. To compile and run the sample, follow these steps:
1. Download a **[sample project](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=Java)**, and then unzip the file.
1. In the command line, navigate to the root directory of the unzipped sample project, and then compile the Java source file:
```bash
javac -cp jar/com.pdftools.jar:. PdfToolsPdf2ImgSimple.java
```
```bash
javac -cp jar/com.pdftools.jar;. PdfToolsPdf2ImgSimple.java
```
1. Run the sample:
```bash
java -cp jar/com.pdftools.jar:bin:. PdfToolsPdf2ImgSimple PdfPrimerWhitepaper.pdf tiff_output.tiff
```
```bash
java -cp jar/com.pdftools.jar;bin;. PdfToolsPdf2ImgSimple PdfPrimerWhitepaper.pdf tiff_output.tiff
```
The code sample takes:
- The input and output files are represented as a file name or a file path with the file name.
- Both file paths (input and output) can be relative or absolute.
Review the following snippet with a placeholder and compare it to the last step of the previous procedure:
```bash
java -cp jar/com.pdftools.jar:bin:. PdfToolsPdf2ImgSimple INPUT_FILE OUTPUT_FILE
```
```bash
java -cp jar/com.pdftools.jar;bin;. PdfToolsPdf2ImgSimple INPUT_FILE OUTPUT_FILE
```
1. Download a **[sample project](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=Java)**, and then unzip the file.
1. From the unzipped file, import the `.project` file into the Eclipse IDE. The source file `PdfToolsPdf2ImgSimple.java` is compiled automatically.
1. Right-click the `java` file, and then select **PdfToolsPdf2ImgSimple.java** > **Run As** > **Run configurations...**.
1. Create a new configuration for a **Java Application**, and then add the required arguments, for example:
```
PdfPrimerWhitepaper.pdf OutputPdfPrimerWhitePaper.tiff
```
:::note
You can apply a similar procedure described in this tutorial for other code samples. For more information, see [Code samples](../../code-samples/pdftools-sdk-samples.mdx) page.
:::
## Integrate the SDK into your application
Integrate and initialize the Pdftools SDK into your application by following the instructions in the following sections.
### Add the SDK to your project
The Pdftools SDK for Java is available on Maven. To add the Pdftools SDK for Java to your project, select your operating system and system architecture and add the following to your `pom.xml`:
```xml
com.pdftools
pdftools-sdk
1.14.0
com.pdftools
pdftools-sdk
1.14.0
linux-x64
so
```
```xml
com.pdftools
pdftools-sdk
1.14.0
com.pdftools
pdftools-sdk
1.14.0
linux-x64-glibc2.12
so
```
```xml
com.pdftools
pdftools-sdk
1.14.0
com.pdftools
pdftools-sdk
1.14.0
linux-arm64
so
```
```xml
com.pdftools
pdftools-sdk
1.14.0
com.pdftools
pdftools-sdk
1.14.0
osx-arm64
dylib
```
```xml
com.pdftools
pdftools-sdk
1.14.0
com.pdftools
pdftools-sdk
1.14.0
osx-x64
dylib
```
```xml
com.pdftools
pdftools-sdk
1.14.0
com.pdftools
pdftools-sdk
1.14.0
win-x64
dll
```
```xml
com.pdftools
pdftools-sdk
1.14.0
com.pdftools
pdftools-sdk
1.14.0
win-x86
dll
```
```xml
com.pdftools
pdftools-sdk
1.14.0
com.pdftools
pdftools-sdk
1.14.0
win-arm64
dll
```
1. Download the [Pdftools SDK for Java](https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSDK/latest/PdfToolsSDK_Java-latest.zip) product kit, and then unzip the file.
2. Add the `jar` file to your project's classpath.
3. Copy the `lib` folder containing the native binary files to your project, for example `/lib`.
### Load the SDK
The Pdftools SDK for Java requires you to load the underlying native binary files suitable for your operating system and system architecture at runtime.
There are two ways how to load the Pdftools SDK for Java with Maven:
1. If you are consuming Java libraries directly from the local Maven repository, load the native binary files using the following code:
```java
System.load(System.getProperty("user.home") + "/.m2/repository/com/pdftools/pdftools-sdk/1.14.0/pdftools-sdk-1.14.0-linux-x64.so");
```
```java
System.load(System.getProperty("user.home") + "/.m2/repository/com/pdftools/pdftools-sdk/1.14.0/pdftools-sdk-1.14.0-linux-x64-glibc2.12.so");
```
```java
System.load(System.getProperty("user.home") + "/.m2/repository/com/pdftools/pdftools-sdk/1.14.0/pdftools-sdk-1.14.0-linux-arm64.so");
```
```java
System.load(System.getProperty("user.home") + "/.m2/repository/com/pdftools/pdftools-sdk/1.14.0/pdftools-sdk-1.14.0-osx-arm64.dylib");
```
```java
System.load(System.getProperty("user.home") + "/.m2/repository/com/pdftools/pdftools-sdk/1.14.0/pdftools-sdk-1.14.0-osx-x64.dylib");
```
```java
System.load(System.getProperty("user.home") + "/.m2/repository/com/pdftools/pdftools-sdk/1.14.0/pdftools-sdk-1.14.0-win-x64.dll");
```
```java
System.load(System.getProperty("user.home") + "/.m2/repository/com/pdftools/pdftools-sdk/1.14.0/pdftools-sdk-1.14.0-win-x86.dll");
```
```java
System.load(System.getProperty("user.home") + "/.m2/repository/com/pdftools/pdftools-sdk/1.14.0/pdftools-sdk-1.14.0-win-arm64.dll");
```
1. Alternatively, use the system library path:
1. Add the Pdftools SDK `lib` directory to the system library path.
- Windows: Environment variable `PATH`
- Linux and macOS: Defined by `LD_LIBRARY_PATH`
- Or specify the path using the VM arg `-Djava.library.path=`.
1. Load the library using:
```java
System.loadLibrary("pdftools-sdk-1.14.0-linux-x64");
```
```java
System.loadLibrary("pdftools-sdk-1.14.0-linux-x64-glibc2.12");
```
```java
System.loadLibrary("pdftools-sdk-1.14.0-linux-arm64");
```
```java
System.loadLibrary("pdftools-sdk-1.14.0-osx-arm64");
```
```java
System.loadLibrary("pdftools-sdk-1.14.0-osx-x64");
```
```java
System.loadLibrary("pdftools-sdk-1.14.0-win-x64");
```
```java
System.loadLibrary("pdftools-sdk-1.14.0-win-x86");
```
```java
System.loadLibrary("pdftools-sdk-1.14.0-win-arm64");
```
In the default configuration of the Pdftools SDK, the `lib` directory has the following structure:
```
lib
├── linux-x64
├── linux-arm64
├── osx-arm64
├── osx-x64
├── win-x64
└── win-x86
└── win-arm64
```
If you are using the default directory structure, load the library from the respective subfolder in `lib` directory appropriate for your operating system and system architecture.
There are two ways to load the Pdftools SDK for Java manually:
1. Load the Pdftools SDK using the system library path:
1. Add the directory for your operating system to the system library path.
- Windows: environment variable `PATH`.
- Linux and macOS: defined by `LD_LIBRARY_PATH`.
- Specify the path using the Java VM argument `-Djava.library.path=`.
1. Load the library from the system's library path by using:
```java
System.loadLibrary("PdfToolsSdk");
```
1. Alternatively, load the Pdftools SDK by specifying the absolute path:
```java
System.load(new File("lib/linux-x64/libPdfToolsSdk.so").getAbsolutePath());
```
```java
System.load(new File("lib/linux-x64/libPdfToolsSdk.so").getAbsolutePath());
```
:::note
Ensure to download a proper package. Native libraries suitable for glibc2.12+ are provided as a [separate download](https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSDK/latest/PdfToolsSDK_glibc2.12-latest.zip).
:::
```java
System.load(new File("lib/linux-arm64/libPdfToolsSdk.so").getAbsolutePath());
```
```java
System.load(new File("lib/osx-arm64/libPdfToolsSdk.dylib").getAbsolutePath());
```
```java
System.load(new File("lib/osx-x64/libPdfToolsSdk.dylib").getAbsolutePath());
```
```java
System.load(new File("lib/win-x64/PdfToolsSdk.dll").getAbsolutePath());
```
```java
System.load(new File("lib/win-x86/PdfToolsSdk.dll").getAbsolutePath());
```
```java
System.load(new File("lib/win-arm64/PdfToolsSdk.dll").getAbsolutePath());
```
:::note
Note the difference between:
* `System.load(..)`: Loads the library from an absolute file path.
* `System.loadLibrary(..)`: Load the library from the system's library path.
:::
:::info
If you are shipping your application, ensure to ship it with the native binary files.
Note that you must load the native binary files from the file system and cannot load them from within a `jar` file or other bundle.
:::
### Optional: Initialize the SDK
Learn how to remove watermarked output of the Pdftools SDK using a valid license key.
:::tip
You can try the Pdftools SDK without a license key for free. This section is **optional** if you want to evaluate this SDK. Initialization only lets you remove watermarks added to output files.
:::
:::info Getting a license key
Contact the Pdftools sales team through the [Contact page](https://www.pdf-tools.com/contact/) to get a full license. For additional information, review [Pdftools SDK license management](/docs/licenses/products/pdf-tools-sdk-license/).
:::
To remove watermarks, follow these steps:
1. Locate your license key. For more information, review [Find the license key](/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key).
1. Before you call any function of the Pdftools SDK, first call the `Sdk.initialize` method.
```java
Sdk.initialize("insert-license-key-here");
```
Replace the `insert-license-key-here` with the value of your license key. Include the less-than (`<`) and greater-than (`>`) signs.
To get a working code sample with the `Sdk.initialize` method that you can use as a reference for your code, follow these steps:
1. On the [Code samples](../../code-samples/pdftools-sdk-samples.mdx) page, download and unzip a Java code sample. For example: Download **[Convert PDF to image](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=Java)** sample.
1. Unzip the file, and then find the `Sdk.initialize` method in the main Java file of the sample. For example: [Convert PDF to image](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=Java) sample includes `SDK.initialize` method in the `PdfToolsPdf2ImgSimple.java` file.
1. Uncomment the method and replace `insert-license-key-here` with your license key.
### Implement your use case
- Find more use cases and sample projects on the [Code samples](../../code-samples/pdftools-sdk-samples.mdx) page.
- For more technical information about the Pdftools SDK for Java, consult the [Java technical notes](../../api-references/technical-notes/java-notes.mdx).
- If you need to configure a proxy, review [Configure proxy](/docs/licenses/products/pdf-tools-sdk-license/#configure-proxy) documentation section.
---
## Get started with other programming languages
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
Use the Pdftools SDK with Go, Rust, and potentially many other programming languages by binding the C API. The Pdftools SDK includes a powerful C API for high-performance applications, which can be used with a wide range of programming languages not directly supported by the Pdftools SDK. This guide illustrates the binding of the C API on a Go example.
Pdftools customers use interface bindings to implement the Pdftools SDK with the following programming languages and frameworks:
- Delphi
- Go
- Lua
- Node.js
- Perl
- PHP
- R
- Ruby
- Rust
:::note
Pdftools do not officially support and cannot guarantee the stability of such interface bindings. This approach requires you to be very familiar with your chosen language and how it integrates with C.
:::
## Prerequisites
Install [Go 1.6](https://go.dev/dl/) or higher on your system, and include the Go executable files in your path.
## Use the Pdftools SDK with Go
Go provides a standard library package [cgo](https://pkg.go.dev/cmd/cgo) which makes it easy to bind the Pdftools SDK's C API. Learn how to use the Go programming language to convert a PDF document to an image in the following example.
:::note
These instructions explain the process by which you create a Go wrapper for the Pdftools SDK. For simplicity, some functionality such as error handling is not shown in the example code below.
:::
1. Create a project directory named `pdf2img`.
2. Extract the latest `Pdftools SDK for C` zip file into the `pdf2img` directory, then rename the extracted directory to `PdftoolsSDK`. The project structure looks like the following:
```
pdf2img
└── PdftoolsSDK
├── include
└── lib
```
3. Create a new file in the top-level project directory and name it `pdf2img.go`, and then add the following code inside it:
```go
package main
// #cgo CFLAGS: -IPdftoolsSDK/include
// #cgo LDFLAGS: -LPdftoolsSDK/lib/win-x64 -Wl,-rpath,PdftoolsSDK/lib/win-x64 -lPdfToolsSdk
// #include "PdfTools_Platform.h"
// #include "PdfTools_PdfTools.h"
// #include "PdfTools_PdfToolsSys.h"
// #include "PdfTools_PdfToolsPdf.h"
// #include "PdfTools_PdfToolsImage.h"
// #include "PdfTools_PdfToolsPdf2Image.h"
// #include "PdfTools_PdfToolsPdf2ImageProfiles.h"
// #include
// #include
import "C"
import (
"os"
"unsafe"
)
func main() {
// Initialize the SDK
C.PdfTools_Initialize()
demokey := C.CString("")
C.PdfTools_Sdk_Initialize(demokey, nil)
szInPath := C.CString(os.Args[1])
szInParms := C.CString("rb")
szOutPath := C.CString(os.Args[2])
szOutParms := C.CString("wb+")
var pInStream *C.FILE
var pOutStream *C.FILE
var pInDoc *C.TPdfToolsPdf_Document
var pOutDoc *C.TPdfToolsImage_Document
var pProfile *C.TPdfToolsPdf2ImageProfiles_Profile
var pConverter *C.TPdfToolsPdf2Image_Converter
// Open input document
pInStream = C.fopen(szInPath, szInParms)
var inDesc *C.TPdfToolsSys_StreamDescriptor
inDesc = (*C.TPdfToolsSys_StreamDescriptor)(C.malloc(C.size_t(unsafe.Sizeof(*inDesc))))
C.PdfToolsSysCreateFILEStreamDescriptor(inDesc, pInStream, 0)
pInDoc = C.PdfToolsPdf_Document_Open(inDesc, C.CString(""))
// Create output stream for writing
pOutStream = C.fopen(szOutPath, szOutParms)
var outDesc *C.TPdfToolsSys_StreamDescriptor
outDesc = (*C.TPdfToolsSys_StreamDescriptor)(C.malloc(C.size_t(unsafe.Sizeof(*outDesc))))
C.PdfToolsSysCreateFILEStreamDescriptor(outDesc, pOutStream, 0)
// Create the profile that defines the conversion parameters.
// The Archive profile converts PDF documents to TIFF images for archiving.
pProfile = (*C.TPdfToolsPdf2ImageProfiles_Profile)(C.PdfToolsPdf2ImageProfiles_Archive_New())
// Convert the PDF document to an image document
pConverter = C.PdfToolsPdf2Image_Converter_New()
pOutDoc =
(*C.TPdfToolsImage_Document)(C.PdfToolsPdf2Image_Converter_ConvertDocument(pConverter, pInDoc, outDesc, pProfile))
// Clean up resources
if pOutDoc != nil {
C.PdfToolsImage_Document_Close(pOutDoc)
}
C.PdfTools_Release(unsafe.Pointer(pConverter))
C.PdfTools_Release(unsafe.Pointer(pProfile))
if pOutStream != nil {
C.fclose(pOutStream)
}
if pInDoc != nil {
C.PdfToolsPdf_Document_Close(pInDoc)
}
if pInStream != nil {
C.fclose(pInStream)
}
C.free(unsafe.Pointer(szInPath))
C.free(unsafe.Pointer(szInParms))
C.free(unsafe.Pointer(szOutPath))
C.free(unsafe.Pointer(szOutParms))
C.PdfTools_Uninitialize()
}
```
```go
package main
// #cgo CFLAGS: -IPdftoolsSDK/include
// #cgo LDFLAGS: -LPdftoolsSDK/lib/linux-x64 -Wl,-rpath,PdftoolsSDK/lib/linux-x64 -lPdfToolsSdk
// #include "PdfTools_Platform.h"
// #include "PdfTools_PdfTools.h"
// #include "PdfTools_PdfToolsSys.h"
// #include "PdfTools_PdfToolsPdf.h"
// #include "PdfTools_PdfToolsImage.h"
// #include "PdfTools_PdfToolsPdf2Image.h"
// #include "PdfTools_PdfToolsPdf2ImageProfiles.h"
// #include
// #include
import "C"
import (
"os"
"unsafe"
)
func main() {
// Initialize the SDK
C.PdfTools_Initialize()
demokey := C.CString("")
C.PdfTools_Sdk_Initialize(demokey, nil)
szInPath := C.CString(os.Args[1])
szInParms := C.CString("rb")
szOutPath := C.CString(os.Args[2])
szOutParms := C.CString("wb+")
var pInStream *C.FILE
var pOutStream *C.FILE
var pInDoc *C.TPdfToolsPdf_Document
var pOutDoc *C.TPdfToolsImage_Document
var pProfile *C.TPdfToolsPdf2ImageProfiles_Profile
var pConverter *C.TPdfToolsPdf2Image_Converter
// Open input document
pInStream = C.fopen(szInPath, szInParms)
var inDesc *C.TPdfToolsSys_StreamDescriptor
inDesc = (*C.TPdfToolsSys_StreamDescriptor)(C.malloc(C.size_t(unsafe.Sizeof(*inDesc))))
C.PdfToolsSysCreateFILEStreamDescriptor(inDesc, pInStream, 0)
pInDoc = C.PdfToolsPdf_Document_Open(inDesc, C.CString(""))
// Create output stream for writing
pOutStream = C.fopen(szOutPath, szOutParms)
var outDesc *C.TPdfToolsSys_StreamDescriptor
outDesc = (*C.TPdfToolsSys_StreamDescriptor)(C.malloc(C.size_t(unsafe.Sizeof(*outDesc))))
C.PdfToolsSysCreateFILEStreamDescriptor(outDesc, pOutStream, 0)
// Create the profile that defines the conversion parameters.
// The Archive profile converts PDF documents to TIFF images for archiving.
pProfile = (*C.TPdfToolsPdf2ImageProfiles_Profile)(C.PdfToolsPdf2ImageProfiles_Archive_New())
// Convert the PDF document to an image document
pConverter = C.PdfToolsPdf2Image_Converter_New()
pOutDoc =
(*C.TPdfToolsImage_Document)(C.PdfToolsPdf2Image_Converter_ConvertDocument(pConverter, pInDoc, outDesc, pProfile))
// Clean up resources
if pOutDoc != nil {
C.PdfToolsImage_Document_Close(pOutDoc)
}
C.PdfTools_Release(unsafe.Pointer(pConverter))
C.PdfTools_Release(unsafe.Pointer(pProfile))
if pOutStream != nil {
C.fclose(pOutStream)
}
if pInDoc != nil {
C.PdfToolsPdf_Document_Close(pInDoc)
}
if pInStream != nil {
C.fclose(pInStream)
}
C.free(unsafe.Pointer(szInPath))
C.free(unsafe.Pointer(szInParms))
C.free(unsafe.Pointer(szOutPath))
C.free(unsafe.Pointer(szOutParms))
C.PdfTools_Uninitialize()
}
```
```go
package main
// #cgo CFLAGS: -IPdftoolsSDK/include
// #cgo LDFLAGS: -LPdftoolsSDK/lib/osx-arm64 -Wl,-rpath,PdftoolsSDK/lib/osx-arm64 -lPdfToolsSdk
// #include "PdfTools_Platform.h"
// #include "PdfTools_PdfTools.h"
// #include "PdfTools_PdfToolsSys.h"
// #include "PdfTools_PdfToolsPdf.h"
// #include "PdfTools_PdfToolsImage.h"
// #include "PdfTools_PdfToolsPdf2Image.h"
// #include "PdfTools_PdfToolsPdf2ImageProfiles.h"
// #include
// #include
import "C"
import (
"os"
"unsafe"
)
func main() {
// Initialize the SDK
C.PdfTools_Initialize()
// If you have a license key for the Pdftools SDK, add it here and un-comment these lines.
// demokey := C.CString("")
// C.PdfTools_Sdk_Initialize(demokey, nil)
szInPath := C.CString(os.Args[1])
szInParms := C.CString("rb")
szOutPath := C.CString(os.Args[2])
szOutParms := C.CString("wb+")
var pInStream *C.FILE
var pOutStream *C.FILE
var pInDoc *C.TPdfToolsPdf_Document
var pOutDoc *C.TPdfToolsImage_Document
var pProfile *C.TPdfToolsPdf2ImageProfiles_Profile
var pConverter *C.TPdfToolsPdf2Image_Converter
// Open input document
pInStream = C.fopen(szInPath, szInParms)
var inDesc *C.TPdfToolsSys_StreamDescriptor
inDesc = (*C.TPdfToolsSys_StreamDescriptor)(C.malloc(C.size_t(unsafe.Sizeof(*inDesc))))
C.PdfToolsSysCreateFILEStreamDescriptor(inDesc, pInStream, 0)
pInDoc = C.PdfToolsPdf_Document_Open(inDesc, C.CString(""))
// Create output stream for writing
pOutStream = C.fopen(szOutPath, szOutParms)
var outDesc *C.TPdfToolsSys_StreamDescriptor
outDesc = (*C.TPdfToolsSys_StreamDescriptor)(C.malloc(C.size_t(unsafe.Sizeof(*outDesc))))
C.PdfToolsSysCreateFILEStreamDescriptor(outDesc, pOutStream, 0)
// Create the profile that defines the conversion parameters.
// The Archive profile converts PDF documents to TIFF images for archiving.
pProfile = (*C.TPdfToolsPdf2ImageProfiles_Profile)(C.PdfToolsPdf2ImageProfiles_Archive_New())
// Convert the PDF document to an image document
pConverter = C.PdfToolsPdf2Image_Converter_New()
pOutDoc =
(*C.TPdfToolsImage_Document)(C.PdfToolsPdf2Image_Converter_ConvertDocument(pConverter, pInDoc, outDesc, pProfile))
// Clean up resources
if pOutDoc != nil {
C.PdfToolsImage_Document_Close(pOutDoc)
}
C.PdfTools_Release(unsafe.Pointer(pConverter))
C.PdfTools_Release(unsafe.Pointer(pProfile))
if pOutStream != nil {
C.fclose(pOutStream)
}
if pInDoc != nil {
C.PdfToolsPdf_Document_Close(pInDoc)
}
if pInStream != nil {
C.fclose(pInStream)
}
C.free(unsafe.Pointer(szInPath))
C.free(unsafe.Pointer(szInParms))
C.free(unsafe.Pointer(szOutPath))
C.free(unsafe.Pointer(szOutParms))
C.PdfTools_Uninitialize()
}
```
:::tip
The output file is watermarked by default. If you have a valid license key, replace `` with your Pdftools SDK license key.
:::
4. Open a terminal in the top-level project directory (`~/pdf2img`) and run:
```
go build
```
5. An executable file named `pdf2img` is created in the top-level project directory. Test the executable by running the command:
```
pdf2img
```
For example, place a PDF file named `in.pdf` in the top-level project directory and run:
```
pdf2img in.pdf out.tif
```
An output image file named `out.tif` is created in the top-level project directory.
## Bind the C library and header files
Bind the Pdftools SDK's C API to a different programming language using the native C library and header files. Click the **[download](https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSDK/latest/PdfToolsSDK_C-latest.zip)** link to get the `Pdftools SDK for C` package.
The method for using the native C library and header files differs slightly for each language.
:::tip
Without a valid license key the output files are watermarked. Get in touch with the Pdftools sales team through the [Contact page](https://www.pdf-tools.com/contact/) to get a full license.
:::
---
## Get started with Python
This guide walks you through the steps to use the Pdftools SDK in a sample project with Python. The Python interface is implemented as a wrapper around the Pdftools SDK's [C API](https://api-reference.pdf-tools.com/pdfsdk/latest/cdoc/files.html).
:::tip
Try the Pdftools SDK without a license key for free.
:::
## Prerequisites
The Pdftools SDK for Python requires **Python 3.6 or higher**.
## Getting started with a sample project
Learn how to use the Pdftools SDK using a Python sample project and convert a PDF file to an image.
### Download and run the sample
1. Download a **[sample project](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=Python)**, and then unzip the file.
1. Install the Pdftools SDK package by running the following command:
```bash
pip install pdftools_sdk
```
1. In the command line, navigate to the root directory of the unzipped sample project, where you can find the `pdf2_img_simple.py` file.
1. To render the sample PDF file `PdfPrimerWhitePaper.pdf` to a multi-page TIFF image format, run:
```shell
python ./pdf2_img_simple.py PdfPrimerWhitePaper.pdf PdfPrimerWhitePaper.tiff
```
:::note
Run `python3` instead on systems where only Python 3 is installed and `python` is not aliased.
:::
The code sample takes:
- The input and output files are represented as a file name or a file path with the file name.
- Both file paths (input and output) can be relative or absolute.
Review the following snippet with a placeholder and compare it to the last step of the previous procedure:
```bash
python ./pdf2_img_simple.py INPUT_PDF IMAGE_OUTPUT_PATH
```
## Integrate the SDK into your application
Integrate and initialize the Pdftools SDK into your application by following the instructions in the following sections.
### Add the SDK to your project
1. Install the Python package:
```shell
pip install pdftools_sdk
```
1. From the [Pdftools SDK code samples](../../code-samples/pdftools-sdk-samples.mdx) page, download any Python code sample.
1. Unzip a code sample and review the `README.md` file with usage details. Every code sample includes a `README.md` with different usage instructions.
1. Import the following packages in the header of your Python code:
```python
from ctypes import *
from pdftools_sdk.pdf import Document
from pdftools_sdk.pdf2_image import Converter
from pdftools_sdk.pdf2_image.profiles import Archive
```
:::info Imports depend on the sample you use
The imports depend on the Python sample you use. Imports displayed in the last step of the previous procedure are valid for the [Convert PDF to image](../../code-samples/pdftools-sdk-samples.mdx#convert-pdf-to-image) sample. Every sample includes a single Python file from which you can copy the imports. In case you want to use another functionality, copy the correct imports into your project with the following steps:
1. Open the [Pdftools SDK code samples](../../code-samples/pdftools-sdk-samples.mdx).
1. Download a sample. For example: [Decrypt an encrypted PDF](../../code-samples/pdftools-sdk-samples.mdx#decrypt-an-encrypted-pdf)
1. Unzip the downloaded sample.
1. Open the `decrypt.py` file, and then copy its imports to the header of your Python code.
:::
### Optional: Initialize the SDK
Learn how to remove watermarked output of the Pdftools SDK using a valid license key.
:::tip
You can try the Pdftools SDK without a license key for free. This section is **optional** if you want to evaluate this SDK. Initialization only lets you remove watermarks added to output files.
:::
:::info Getting a license key
Contact the Pdftools sales team through the [Contact page](https://www.pdf-tools.com/contact/) to get a full license. For additional information, review [Pdftools SDK license management](/docs/licenses/products/pdf-tools-sdk-license/).
:::
To remove watermarks, follow these steps:
1. Locate your license key. For more information, review [Find the license key](/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key).
1. Before you call any function of the Pdftools SDK, first call the `Sdk.initialize` method.
```python
Sdk.initialize("insert-license-key-here")
```
Replace the `insert-license-key-here` with the value of your license key. Include the less-than (`<`) and greater-than (`>`) signs.
To get a code sample with the `PdfTools_Sdk_Initialize` function that you can use as a reference for your code, follow these steps:
1. On the [Code samples](../../code-samples/pdftools-sdk-samples.mdx) page, download and unzip a Python code sample. For example: Download **[Convert PDF to image](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=Python)** sample.
1. Unzip the file, and then find the `Sdk.initialize` method in a Python file included with the sample. For example: [Convert PDF to image](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=Python) sample includes `SDK.initialize` method in the `pdf2_img_simple.py` file.
1. Uncomment the method and replace `insert-license-key-here` with your license key.
### Implement your use case
- Find more use cases and sample projects on the [Code samples](../../code-samples/pdftools-sdk-samples.mdx) page.
- If you need to configure a proxy, review [Configure proxy](/docs/licenses/products/pdf-tools-sdk-license/#configure-proxy) documentation section.
---
## Pdftools SDK Shell Tool
Learn how to use the Pdftools SDK and the Toolbox add-on from the command line with the Pdftools SDK Shell Tool.
## Prerequisites
The Pdftools SDK Shell Tool is available as:
- Self-contained .NET distribution.
- Framework-dependent .NET distribution.
Use the self-contained distribution if you do not have the .NET framework installed. The framework-dependent distribution of the Pdftools SDK Shell Tool requires you to install [**.NET 6.0**](https://dotnet.microsoft.com/en-us/download) or higher.
## Download
Download the latest version of the Pdftools SDK shell tool for the following platforms:
| Platform | Self-contained distribution | Framework-dependent distribution |
|------------|-----------------------------|----------------------------------|
| linux-x64 | [PdfToolsSDK_Shell-latest-linux-x64-self-contained.zip](https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSHELL/latest/PdfToolsSDK_Shell-latest-linux-x64-self-contained.zip) | [PdfToolsSDK_Shell-latest-linux-x64.zip](https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSHELL/latest/PdfToolsSDK_Shell-latest-linux-x64.zip) |
| linux-arm64| [PdfToolsSDK_Shell-latest-linux-arm64-self-contained.zip](https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSHELL/latest/PdfToolsSDK_Shell-latest-linux-arm64-self-contained.zip) | [PdfToolsSDK_Shell-latest-linux-arm64.zip](https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSHELL/latest/PdfToolsSDK_Shell-latest-linux-arm64.zip) |
| osx-x64 | [PdfToolsSDK_Shell-latest-osx-x64-self-contained.zip](https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSHELL/latest/PdfToolsSDK_Shell-latest-osx-x64-self-contained.zip) | [PdfToolsSDK_Shell-latest-osx-x64.zip](https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSHELL/latest/PdfToolsSDK_Shell-latest-osx-x64.zip) |
| osx-arm64 | [PdfToolsSDK_Shell-latest-osx-arm64-self-contained.zip](https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSHELL/latest/PdfToolsSDK_Shell-latest-osx-arm64-self-contained.zip) | [PdfToolsSDK_Shell-latest-osx-arm64.zip](https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSHELL/latest/PdfToolsSDK_Shell-latest-osx-arm64.zip) |
| win-x64 | [PdfToolsSDK_Shell-latest-win-x64-self-contained.zip](https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSHELL/latest/PdfToolsSDK_Shell-latest-win-x64-self-contained.zip) | [PdfToolsSDK_Shell-latest-win-x64.zip](https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSHELL/latest/PdfToolsSDK_Shell-latest-win-x64.zip) |
| win-arm64 | [PdfToolsSDK_Shell-latest-win-arm64-self-contained.zip](https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSHELL/latest/PdfToolsSDK_Shell-latest-win-arm64-self-contained.zip) | [PdfToolsSDK_Shell-latest-win-arm64.zip](https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSHELL/latest/PdfToolsSDK_Shell-latest-win-arm64.zip) |
:::tip Older Linux systems
Separate binary files are available that support older Linux distributions using glibc2.12+. You can download these binary files from [PdfToolsSDK_glibc2.12-latest.zip](https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSDK/latest/PdfToolsSDK_glibc2.12-latest.zip).
:::
## Features
:::note
As of this version, the Pdftools SDK Shell Tool supports the following features of the Pdftools SDK.
Support for additional features will be added soon.
:::
| Feature | Description | Support as of version |
|------------------------------|-------------------------------------------------------------------------------|-----------------------|
| Image to PDF | Convert images to single PDF or PDF/A | 1.0.0 + |
| PDF to PDF/A | Validate PDF conformance; Convert documents to PDF/A | 1.2.0 + |
| Compression and optimization | Compress and optimize PDF documents for web, archiving, printing or file size | 1.0.0 + |
| Security | Sign, certify PDF documents; Validate signatures in PDF documents | 1.4.0+ |
| Rendering | Render PDF documents to images for fax, archive, or viewing | 1.1.0+ |
| Merging and splitting | Merge and split PDF documents to assemble new output documents | 1.1.0+ |
## Usage
The general usage is
```bash
> pdf [sdk_options] [: ] [ [output_options]]
```
### Chaining commands
:::tip
You can chain multiple commands using `:`. This way you can apply multiple operations without the need to store each result to an intermediate file.
:::
Example:
```bash
> pdf input.jpg import : optimize-web out.pdf
```
### Detailed help
For the full reference of commands and features of the Pdftools SDK Shell Tool use the built-in help by executing:
```bash
# For all commands and features
pdf help
# For specific commands
pdf help
```
### Use of license key
To use a license key and remove the watermarked results, insert the license key using the `-lk` parameter:
```shell
> pdf -lk ""
```
Substitute:
- `` with the value of your license key.
- `` with a path to the input file.
- `` with a specific command.
- `` with a path to the output file.
For example:
```shell
> pdf -lk "" input.jpg import : optimize-web out.pdf
```
---
## Getting started with the Toolbox add-on
import DocCardList from '@theme/DocCardList';
Welcome to the Toolbox add-on getting started guides. The Toolbox add-on is a library that provides functionality for developers who need low-level access to the content of PDF files. Guides for C, .NET, and Java explain how to work with a sample project, and then walk you through the steps necessary to integrate the SDK into your application.
```
C:\Program Files\PDF Tools AG\
```
Included subdirectories are:
| Subdirectory | Description |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `lib` | Runtime executable binaries and runtime import libraries: win-x86\PdfTools_Toolbox.dll and win-x86\PdfTools_Toolbox.lib for 32-bit Windows.win-x64\PdfTools_Toolbox.dll and win-x64\PdfTools_Toolbox.lib for 64-bit Windows.win-arm64\PdfTools_Toolbox.dll and win-arm64\PdfTools_Toolbox.lib for 64-bit Windows ARM. |
| `include` | Header files to add to your C or C++ project. The main header `PdfTools_Toolbox.h` includes all the other headers. |
```
/opt/pdftools.com/
```
Included subdirectories are:
| Subdirectory | Description |
| ------------ | ------------------------------------------------------------------------------------------------------------------------ |
| `lib` | Runtime executable binaries for all supported platforms: linux-x64/libPdfToolsSdk.so for 64-bit Linuxlinux-arm64/libPdfToolsSdk.so for 64-bit Linux ARM |
| `include` | Header files to add to your C or C++ project. The main header `PdfTools_Toolbox.h` includes all the other headers. |
```
/opt/pdftools.com/
```
Included subdirectories are:
| Subdirectory | Description |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `lib` | Runtime executable binaries: `osx-x64/libPdfTools_Toolbox.dylib` for 64-bit (Intel) macOS `osx-arm64/libPdfTools_Toolbox.dylib` for ARM (Apple Silicon) macOS |
| `include` | Header files to add to your C or C++ project. The main header PdfTools_Toolbox.h includes all the other headers. |
1. Optional: The native libraries must be available in your compiler's library path. This step is only required if your build process doesn't resolve it automatically:
Add the `lib\win-x64`, `lib\win-arm64` or `lib\win-x86` subdirectory to the `%PATH%` environment variable.
Create a link to the shared library from one of the standard library directories, e.g:
```
ln -s /opt/pdf-tools.com/lib/linux-x64/libPdfTools_Toolbox.so /usr/lib
```
Create a link to the shared library from one of the standard library directories. For example (for an Intel processor Mac):
```
ln -s /opt/pdf-tools.com/lib/osx-x64/libPdfTools_Toolbox.dylib /usr/lib
```
### Initialize the SDK
The Toolbox add-on always requires a license key to operate (unlike the Pdftools SDK).
:::tip Getting a license key
Without a valid license key the Toolbox add-on returns an error. Get in touch with the Pdftools sales team through the [Contact page](https://www.pdf-tools.com/contact/) to get a full license.
:::
To initialize the Toolbox add-on with your license key, follow these steps:
1. Locate your license key. For more information, review [Find the license key](/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key).
1. Before you call any function of the Toolbox add-on, first call the `Ptx_Sdk_Initialize` function:
```c
GOTO_CLEANUP_IF_FALSE_PRINT_ERROR(Ptx_Sdk_Initialize(_T("insert-license-key-here"), NULL),
_T("Failed to set license key. %s (ErrorCode: 0x%08x).\n"), szErrorBuff,
Ptx_GetLastError());
```
Replace `insert-license-key-here` with the value of your license key. Use the license key in the same format as you copied it. Include the less-than (`<`) and greater-than (`>`) signs.
To get a code sample with the `Ptx_Sdk_Initialize` function that you can use as a reference for your code, follow these steps:
1. On the [Code samples](../../code-samples/pdftools-sdk-toolbox-samples.mdx) page, download and unzip a C code sample. For example: Download **[Extract all images and image masks from a PDF](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ImageExtraction/Download?technology=C)** sample.
1. Unzip the file, and then find the `Ptx_Sdk_Initialize` function in the C file of the sample. For example: [Extract all images and image masks from a PDF](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ImageExtraction/Download?technology=C) includes the `Ptx_Sdk_Initialize` method in the `toolboximageextraction.c` file.
1. Replace the `insert-license-key-here` with your license key.
### Uninitialize the SDK
After processing files with the Toolbox add-on, call the `Uninitialize` function to unload the library correctly:
```c
// Uninitialize library
Ptx_Uninitialize();
```
### Implement your use case
- Find more use cases and sample projects on the Toolbox add-on [Code samples](../../code-samples/pdftools-sdk-toolbox-samples.mdx) page.
- For more technical information about the Toolbox add-on for C, consult the [C technical notes](../../api-references/technical-notes/c-notes.mdx).
---
## Get started with .NET(Toolbox)
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
This guide walks you through the steps to use a sample project, and then explains how to integrate the Toolbox add-on into your application with .NET.
## Request trial or full license
Unlike the Pdftools SDK or the Pdftools SDK Shell Tool, the Toolbox add-on requires a license key for both evaluation and full use. To request a license key, follow these steps:
1. Reach out to the sales team through the [Contact page](https://www.pdf-tools.com/contact/) and mark the Toolbox add-on as the product of your interest for a trial license.
If you already have a license key and you need to copy it, review [Find the license key](/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key).
## Prerequisites
The Toolbox add-on for .NET requires **.NET and .NET Core 2.0 or higher**, or **.NET Framework 4.6.1 or higher**.
## Getting started with a sample project
Learn how to use Toolbox add-on using a C# sample project and extract all images and image masks from a PDF document.
### Compile and run the sample
Switch between the following tabs to display steps for the command line interface or for the Visual Studio. To compile and run the sample, follow these steps:
1. Download a **[sample project](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ImageExtraction/Download?technology=CS)**, and then unzip the file.
1. Locate your license key. For more information, review [Find the license key](/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key).
1. In the `Program.cs` file, replace the string `"insert-license-key-here"` with your license key:
```csharp
Sdk.Initialize("insert-license-key-here", null);
```
Use the license key in the same format as you copied it. Include the less-than (`<`) and greater-than (`>`) signs.
1. In the command line, navigate to the root directory of the unzipped sample project.
1. To extract all images and image masks from the sample PDF file `ImageCollection.pdf` to the output directory `/tmp/images`, run the compiled sample application:
```shell
dotnet run --framework net6.0 --project ToolboxImageExtraction.csproj ImageCollection.pdf /tmp/images
```
The code sample takes:
- The input and output files represented as a file name, a file path with the file name, or the output directory.
- Both file paths (input and output) can be relative or absolute.
Review the following snippet with a placeholder and compare it to the last step of the previous procedure:
```shell
dotnet run --framework net6.0 --project ToolboxImageExtraction.csproj INPUT_FILE OUTPUT_DIRECTORY
```
:::info
This documentation uses Visual Studio 2022.
:::
1. Download a **[sample project](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ImageExtraction/Download?technology=CS)**, and then unzip the file.
1. In the sample folder, double click `ToolboxImageExtraction.csproj`
1. In the `Program.cs` file, replace the string `"insert-license-key-here"` with your license key:
```csharp
Sdk.Initialize("insert-license-key-here", null);
```
1. Click **Build** -> **Build Solution** to compile the project.
1. To extract all images and image masks from the sample PDF file `ImageCollection.pdf` to the output directory `/tmp/images`, run the compiled sample application:
```shell
ToolboxImageExtraction ImageCollection.pdf /tmp/images
```
The code sample takes:
- The input and output files represented as a file name, a file path with the file name, or the output directory.
- Both file paths (input and output) can be relative or absolute.
Review the following snippet with a placeholder and compare it to the last step of the previous procedure:
```shell
ToolboxImageExtraction INPUT_FILE OUTPUT_DIRECTORY
```
:::tip
You can apply a similar procedure described in this tutorial for other code samples. For more information, see [Code samples](../../code-samples/pdftools-sdk-toolbox-samples.mdx) page.
:::
## Integrate the Toolbox add-on into your application
Integrate and initialize the Toolbox add-on into your application by following the instructions in the next sections.
### Add the Toolbox add-on to your project
In the project directory, run the following command:
```shell
dotnet add package PdfTools.Toolbox
```
Optional: If you want to use a specific version of the Pdftools SDK, run the following command:
```shell
dotnet add package PdfTools.Toolbox --version
```
:::info
The integration section describes the process using Visual Studio 2022 on Windows.
:::
1. Open your solution in Visual Studio.
1. Click **Tools** > **Nuget Package Manager** > **Manage NuGet Packages for Solution...**.
1. Click the **Search** tab and search for `PdfTools.Toolbox`.
1. Select the NuGet package named `PdfTools.Toolbox by PDF Tools AG`, select your Project, and then click **Install**.
1. Click **OK** to allow the changes, and then review and **Accept** the license agreement.
### Initialize the SDK
The Toolbox add-on always requires a license key to operate (unlike the Pdftools SDK).
:::tip Getting a license key
Without a valid license key the Toolbox add-on returns an error. Get in touch with the Pdftools sales team through the [Contact page](https://www.pdf-tools.com/contact/) to get a full license.
:::
To initialize the Toolbox add-on with your license key, follow these steps:
1. Locate your license key. For more information, review [Find the license key](/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key).
1. Before you call any function of the Toolbox add-on, first call the `Sdk.initialize` method.
```csharp
Sdk.Initialize("insert-license-key-here", null);
```
Replace `insert-license-key-here` with the value of your license key. Use the license key in the same format as you copied it. Include the less-than (`<`) and greater-than (`>`) signs.
To get a code sample with the `Sdk.Initialize` method that you can use as a reference for your code, follow these steps:
1. On the [Code samples](../../code-samples/pdftools-sdk-toolbox-samples.mdx) page, download and unzip a C# code sample. For example: Download **[Extract all images and image masks from a PDF](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ImageExtraction/Download?technology=CS)** sample.
1. Unzip the file, and then find the `Sdk.initialize` method in the C# file of the sample. For example: [Extract all images and image masks from a PDF](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ImageExtraction/Download?technology=CS) includes the `SDK.initialize` method in the `Program.cs` file.
1. Replace the `insert-license-key-here` with your license key.
### Implement your use case
- Find more use cases and sample projects on the Toolbox add-on [Code samples](../../code-samples/pdftools-sdk-toolbox-samples.mdx) page.
- For more technical information about the Toolbox add-on for .NET, consult the [.NET technical notes](../../api-references/technical-notes/dotnet-notes.mdx).
---
## Get started with Java(Toolbox)
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
This guide walks you through the steps to use a sample project, and then explains how to integrate the Toolbox add-on into your application with the Java programming language.
## Request trial or full license
Unlike the Pdftools SDK or the Pdftools SDK Shell Tool, the Toolbox add-on requires a license key for both evaluation and full use. To request a license key, follow these steps:
1. Reach out to the sales team through the [Contact page](https://www.pdf-tools.com/contact/) and mark the Toolbox add-on as the product of your interest for a trial license.
If you already have a license key and you need to copy it, review [Find the license key](/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key).
## Prerequisites
The Toolbox add-on for Java requires **Java version 8 or higher**.
## Getting started with a sample project
Learn how to use Toolbox add-on using a Java sample project and extract all images and image masks from a PDF document.
### Compile and run the sample
To compile and run the sample, follow these steps:
1. Download a **[sample project](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ImageExtraction/Download?technology=Java)**, and then unzip the file.
1. Locate your license key. For more information, review [Find the license key](/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key).
1. In the `ToolboxImageExtraction.java` file, replace the string `"insert-license-key-here"` with your license key:
```Java
Sdk.initialize("insert-license-key-here", null);
```
Use the license key in the same format as you copied it. Include the less-than (`<`) and greater-than (`>`) signs.
1. In the command line, navigate to the root directory of the unzipped sample project.
1. Create an output directory:
```
mkdir output_images
```
1. Compile the Java source file:
```bash
javac -cp jar/com.pdftools.toolbox.jar:. ToolboxImageExtraction.java
```
```bash
javac -cp jar/com.pdftools.toolbox.jar;. ToolboxImageExtraction.java
```
1. To extract all images and image masks from the sample PDF file `ImageCollection.pdf` to the output directory `/output_images`, run the following command:
```bash
java -cp jar/com.pdftools.toolbox.jar:bin:. ToolboxImageExtraction ImageCollection.pdf /output_images
```
```bash
java -cp jar/com.pdftools.toolbox.jar;bin;. ToolboxImageExtraction ImageCollection.pdf /output_images
```
The code sample takes:
- The input and output files represented as a file name, a file path with the file name, or the output directory.
- Both file paths (input and output) can be relative or absolute.
Review the following snippet with a placeholder and compare it to the last step of the previous procedure:
```bash
java -cp jar/com.pdftools.toolbox.jar:bin:. ToolboxImageExtraction INPUT_FILE OUTPUT_DIRECTORY
```
```bash
java -cp jar/com.pdftools.toolbox.jar;bin;. ToolboxImageExtraction INPUT_FILE OUTPUT_DIRECTORY
```
:::note
You can apply a similar procedure described in this tutorial for other code samples. For more information, see [Code samples](../../code-samples/pdftools-sdk-toolbox-samples.mdx) page.
:::
## Integrate the SDK into your application
Integrate and initialize the Pdftools SDK into your application by following the instructions in the following sections.
### Add the SDK to your project
The Toolbox add-on for Java is available on Maven. To add the Toolbox add-on for Java to your project, select your operating system and system architecture and add the following to your `pom.xml`:
```xml
com.pdftools
toolbox
1.11.0
com.pdftools
toolbox
1.11.0
linux-x64
so
```
```xml
com.pdftools
toolbox
1.11.0
com.pdftools
toolbox
1.11.0
linux-arm64
so
```
```xml
com.pdftools
toolbox
1.11.0
com.pdftools
toolbox
1.11.0
osx-arm64
dylib
```
```xml
com.pdftools
toolbox
1.11.0
com.pdftools
toolbox
1.11.0
osx-x64
dylib
```
```xml
com.pdftools
toolbox
1.11.0
com.pdftools
toolbox
1.11.0
win-x64
dll
```
```xml
com.pdftools
toolbox
1.11.0
com.pdftools
toolbox
1.11.0
win-x86
dll
```
```xml
com.pdftools
toolbox
1.11.0
com.pdftools
toolbox
1.11.0
win-arm64
dll
```
1. Download the [Toolbox add-on for Java](https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSDKXT/latest/PdfTools_Toolbox_Java-latest.zip) product kit, and then unzip the file.
2. Add the `jar` file to your project's classpath.
3. Copy the `lib` folder containing the native binary files to your project, for example `/lib`.
### Load the Toolbox add-on
The Toolbox add-on for Java requires you to load the underlying native binary files suitable for your operating system and system architecture at runtime.
There are two ways how to load the Toolbox add-on for Java with Maven:
1. If you are consuming Java libraries directly from the local Maven repository, load the native binary files using the following code:
```java
System.load(System.getProperty("user.home") + "/.m2/repository/com/pdftools/toolbox/1.11.0/toolbox-1.11.0-linux-x64.so");
```
```java
System.load(System.getProperty("user.home") + "/.m2/repository/com/pdftools/toolbox/1.11.0/toolbox-1.11.0-linux-arm64.so");
```
```java
System.load(System.getProperty("user.home") + "/.m2/repository/com/pdftools/toolbox/1.11.0/toolbox-1.11.0-osx-arm64.dylib");
```
```java
System.load(System.getProperty("user.home") + "/.m2/repository/com/pdftools/toolbox/1.11.0/toolbox-1.11.0-osx-x64.dylib");
```
```java
System.load(System.getProperty("user.home") + "/.m2/repository/com/pdftools/toolbox/1.11.0/toolbox-1.11.0-win-x64.dll");
```
```java
System.load(System.getProperty("user.home") + "/.m2/repository/com/pdftools/toolbox/1.11.0/toolbox-1.11.0-win-x86.dll");
```
```java
System.load(System.getProperty("user.home") + "/.m2/repository/com/pdftools/toolbox/1.11.0/toolbox-1.11.0-win-arm64.dll");
```
1. Alternatively, use the system library path:
1. Add the Toolbox add-on `lib` directory to the system library path.
- Windows: Environment variable `PATH`
- Linux and macOS: Defined by `LD_LIBRARY_PATH`
- Or specify the path using the VM arg `-Djava.library.path=`.
1. Load the library using:
```java
System.loadLibrary("toolbox-1.11.0-linux-x64");
```
```java
System.loadLibrary("toolbox-1.11.0-linux-arm64");
```
```java
System.loadLibrary("toolbox-1.11.0-osx-arm64");
```
```java
System.loadLibrary("toolbox-1.11.0-osx-x64");
```
```java
System.loadLibrary("toolbox-1.11.0-win-x64");
```
```java
System.loadLibrary("toolbox-1.11.0-win-x86");
```
```java
System.loadLibrary("toolbox-1.11.0-win-arm64");
```
In the default configuration of the Toolbox add-on, the `lib` directory has the following structure:
```
lib
├── linux-x64
├── linux-arm64
├── osx-arm64
├── osx-x64
├── win-x64
└── win-x86
└── win-arm64
```
If you are using the default directory structure, load the library from the respective subfolder in `lib` directory appropriate for your operating system and system architecture.
There are two ways to load the Toolbox add-on for Java manually:
1. Load the Toolbox add-on using the system library path:
1. Add the directory for your operating system to the system library path.
- Windows: environment variable `PATH`.
- Linux and macOS: defined by `LD_LIBRARY_PATH`.
- Specify the path using the Java VM argument `-Djava.library.path=`.
1. Load the library from the system's library path by using:
```java
System.loadLibrary("PdfTools_Toolbox");
```
1. Alternatively, load the Toolbox add-on by specifying the absolute path:
```java
System.load(new File("lib/linux-x64/libPdfTools_Toolbox.so").getAbsolutePath());
```
```java
System.load(new File("lib/linux-arm64/libPdfTools_Toolbox.so").getAbsolutePath());
```
```java
System.load(new File("lib/osx-arm64/libPdfTools_Toolbox.dylib").getAbsolutePath());
```
```java
System.load(new File("lib/osx-x64/libPdfTools_Toolbox.dylib").getAbsolutePath());
```
```java
System.load(new File("lib/win-x64/PdfTools_Toolbox.dll").getAbsolutePath());
```
```java
System.load(new File("lib/win-x86/PdfTools_Toolbox.dll").getAbsolutePath());
```
```java
System.load(new File("lib/win-arm64/PdfTools_Toolbox.dll").getAbsolutePath());
```
:::note
Note the difference between:
* `System.load(..)`: Loads the library from an absolute file path.
* `System.loadLibrary(..)`: Load the library from the system's library path.
:::
:::info
If you are shipping your application, ensure to ship it with the native binary files.
Note that you must load the native binary files from the file system and cannot load them from within a `jar` file or other bundle.
:::
### Initialize the SDK
The Toolbox add-on always requires a license key to operate (unlike the Pdftools SDK).
:::tip Getting a license key
Without a valid license key the Toolbox add-on returns an error. Get in touch with the Pdftools sales team through the [Contact page](https://www.pdf-tools.com/contact/) to get a full license.
:::
To initialize the Toolbox add-on with your license key, follow these steps:
1. Locate your license key. For more information, review [Find the license key](/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key).
1. Before you call any function of the Toolbox add-on, first call the `Sdk.initialize` method.
```java
Sdk.initialize("insert-license-key-here", null);
```
Replace `insert-license-key-here` with the value of your license key. Use the license key in the same format as you copied it. Include the less-than (`<`) and greater-than (`>`) signs.
To get a code sample with the `Sdk.initialize` method that you can use as a reference for your code, follow these steps:
1. On the [Code samples](../../code-samples/pdftools-sdk-toolbox-samples.mdx) page, download and unzip a Java code sample. For example: Download **[Extract all images and image masks from a PDF](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ImageExtraction/Download?technology=Java)** sample.
1. Unzip the file, and then find the `Sdk.initialize` method in the main Java file of the sample. For example: [Extract all images and image masks from a PDF](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ImageExtraction/Download?technology=Java) sample includes `SDK.initialize` method in the `ToolboxImageExtraction.java` file.
1. Replace `insert-license-key-here` with your license key.
### Implement your use case
- Find more use cases and sample projects on the [Code samples](../../code-samples/pdftools-sdk-toolbox-samples.mdx) page.
- For more technical information about the Pdftools SDK for Java, consult the [Java technical notes](../../api-references/technical-notes/java-notes.mdx).
---
## Get started with Python(Toolbox)
This guide walks you through the steps to use the Toolbox add-on in a sample project with Python.
:::info
The Python interface is implemented as a wrapper around the Toolbox add-on C API. For more details about specific functions and properties, review the [C API reference](https://api-reference.pdf-tools.com/pdfsdkxt/1.1/cdoc/files.html) documentation.
:::
## Request trial or full license
Unlike the Pdftools SDK or the Pdftools SDK Shell Tool, the Toolbox add-on requires a license key for both evaluation and full use. To request a license key, follow these steps:
1. Reach out to the sales team through the [Contact page](https://www.pdf-tools.com/contact/) and mark the Toolbox add-on as the product of your interest for a trial license.
If you already have a license key and you need to copy it, review [Find the license key](/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key).
## Prerequisites
The Toolbox add-on for Python requires **Python 3.6 or higher**.
## Getting started with a sample project
Learn how to use the Toolbox add-on using a Python sample project and add text to a PDF.
### Download and run the sample
1. Download a **[sample project](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/AddText/Download?technology=Python)**, and then unzip the file.
1. Locate your license key. For more information, review [Find the license key](/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key).
1. In the code sample folder, open the Python file (for example `add_text.py`).
1. In the `add_text.py` file, replace the string `"insert-license-key-here"` with your license key:
```python
# Set and check license key. If the license key is not valid, an exception is thrown.
Sdk.initialize("insert-license-key-here", None)
```
Use the license key in the same format as you copied it. Include the less-than (`<`) and greater-than (`>`) signs.
1. Install the package for the Toolbox add-on by executing:
```bash
pip install pdftools_toolbox
```
1. In the command line, navigate to the root directory of the unzipped sample project, where `add_text.py` resides.
1. To add the text string "Hello World!" to the first page of the PDF file `BlankNoneNoTP.pdf`, run:
```shell
python ./add_text.py BlankNoneNoTP.pdf "Hello World!" output.pdf
```
:::note
Run `python3` instead on systems where only Python 3 is installed and `python` is not aliased.
:::
The code sample takes:
- The input and output files represented as a file name, a file path with the file name, or the output directory.
- Both file paths (input and output) can be relative or absolute.
- The text to be added to the output PDF, written between double quotation marks.
Review the following snippet with a placeholder and compare it to the last step of the previous procedure:
```bash
python ./add_text.py INPUT_FILE "TEXT_TO_BE_ADDED" OUTPUT_FILE
```
## Integrate the Toolbox add-on into your application
Integrate and initialize the Toolbox add-on into your application by following the instructions in the next sections.
### Add the Toolbox add-on to your project
To add the Toolbox add-on to your project, follow these steps:
1. Install the package for the Toolbox add-on by executing:
```shell
pip install pdftools_toolbox
```
1. From the [Toolbox add-on code samples](../../code-samples/pdftools-sdk-toolbox-samples.mdx) page, download any Python code sample.
1. Unzip a code sample and review the `README.md` file with usage details. Every code sample includes a `README.md` with different usage instructions.
1. Import the following packages in the header of your Python code:
```python
from pdftools_toolbox.sdk import Sdk
from pdftools_toolbox.geometry.real import Point
from pdftools_toolbox.pdf import Document, FileReference, Metadata, PageCopyOptions, Page, PageList
from pdftools_toolbox.pdf.content import Font, ContentGenerator, IccBasedColorSpace, Text, TextGenerator
from pdftools_toolbox.pdf.navigation import ViewerSettings
```
:::info Imports depend on the sample you use
The imports depend on the Python sample you use. Imports displayed in the last step of the previous procedure are valid for the [Add text to PDF](../../code-samples/pdftools-sdk-toolbox-samples.mdx#add-text-to-pdf) sample. Every sample includes a single Python file from which you can copy the imports. In case you want to use another functionality, copy the correct imports into your project with the following steps:
1. Open the [Toolbox add-on code samples](../../code-samples/pdftools-sdk-toolbox-samples.mdx).
1. Download a sample. For example: [Place multiple pages on one page](../../code-samples/pdftools-sdk-toolbox-samples.mdx#place-multiple-pages-on-one-page)
1. Unzip the downloaded sample.
1. Open the `multiple_up.py` file, and then copy its imports to the header of your Python code.
:::
### Initialize the Toolbox add-on
The Toolbox add-on always requires a license key to operate (unlike the Pdftools SDK).
:::tip Getting a license key
Without a valid license key the Toolbox add-on returns an error. Get in touch with the Pdftools sales team through the [Contact page](https://www.pdf-tools.com/contact/) to get a full license.
:::
To initialize the Toolbox add-on with your license key, follow these steps:
1. Locate your license key. For more information, review [Find the license key](/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key).
1. Before you call any function of the Toolbox add-on, first call the `Sdk.initialize` method.
```python
Sdk.initialize("insert-license-key-here", None)
```
Replace `insert-license-key-here` with the value of your license key. Use the license key in the same format as you copied it. Include the less-than (`<`) and greater-than (`>`) signs.
To get a code sample with the `Sdk.Initialize` method that you can use as a reference for your code, follow these steps:
1. On the [Code samples](../../code-samples/pdftools-sdk-toolbox-samples.mdx) page, download and unzip a Python code sample. For example: Download **[Add text to PDF](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/AddText/Download?technology=Python)** sample.
1. Unzip the file, and then find the `Sdk.initialize` method in the Python file of the sample. For example: [Add text to PDF](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/AddText/Download?technology=Python) includes the `SDK.initialize` method in the `add_text.py` file.
1. Replace the `insert-license-key-here` with your license key.
### Implement your use case
Download other sample projects that show you how to implement specific use cases with the Toolbox add-on using Python. Review the [Toolbox add-on code samples](../../code-samples/pdftools-sdk-toolbox-samples.mdx) page.
---
## Compress and optimize PDF documents
The Pdftools SDK lets you optimize PDF documents to suit specific target needs such as electronic document exchange, archiving, or printing.
Many processes produce PDF documents that may not be optimized for their specific target application.
For example, the file size may deteriorate download times, or the same font embedded multiple times may impede printing.
With the Pdftools SDK, you can easily configure the process through [optimization profiles](./optimization-profiles.mdx) and determine specific output through various configuration options.
The Pdftools SDK reads an input document and writes the corresponding output document.
Depending on the configured optimization options, various parts of the PDF are processed as required.
The SDK is capable of removing redundant or alternative information, subsetting and merging font programs, downsampling images, and intelligently choosing optimal compression algorithms.
Depending on the desired output, you can [compress and optimize images](#compress-and-optimize-images), [fonts](#optimize-fonts), [page content and document structure](#compress-and-optimize-content-and-structure).
You can set the minimum PDF version of the output file. You can get a log report on the PDF file, listing fonts and images and their respective properties, and extract the number of pages.
{/*TODO Include information on how to get log reports for optimization*/}
## Compress and optimize images
Images can increase file size significantly. The Pdftools SDK optimizes image objects, letting you configure image compression by image type, choose the compression algorithm and compression quality, set color management options such as color profiles and color channels, and convert or remove image objects partially or completely.
**Compression process**
- Separately configure compression of bitonal, indexed, and continuous (i.e. color and grayscale) images
- Define threshold in dots per inch (DPI) for triggering image downsampling
- Define target image resolution in DPI for image downsampling
- Automatically select best compression type for each image
- Configure enforcement of configured compression types
**Image object handling**
- Perform mixed raster content (MRC) optimization for images
- Convert soft masks to image masks if applicable
- Remove invisible parts of images
- Remove images entirely and substitute by empty XObjects
**Color management**
- Choose color management engine
- Reduce the number of color channels used for images, image masks, and soft masks, if applicable
- Convert colors to CMYK, RGB, or grayscale
## Optimize fonts
If your PDF documents do not need to be edited, then there is no need to embed a font as a binary stream in the PDF document.
You can subset font programs, removing all unused glyphs that are not needed to reproduce the document. You can determine when to remove standard fonts and when to merge fonts and font programs.
- Subset font programs to contain only the used glyphs
- Merge compatible font programs and fonts
- Compress Type 1 fonts (convert to CFF)
- Remove font programs
## Compress and optimize content and structure
Unnecessary objects increase file size without reason. With the Pdftools SDK, you can remove these unused, redundant and unwanted objects to reduce file size and speed up rendering.
- Remove unused resources
- Optimize page content automatically
- Flatten or remove page annotations and form fields
- Remove unecessary data:
- Redundant objects
- Embedded standard fonts (e.g. Courier, Arial, Times)
- Embedded, non-symbolic fonts
- Unnecessary file information
- Article threads
- Alternative images
- Metadata
- Page-piece information
- Output intent
- Signature appearances
- Document structure tree, including markup
- Miniature page preview images
- Spider (web capture) information
:::tip Get started
Learn **[how to optimize a PDF document](optimize-a-pdf.mdx)** for a specific use.
:::
---
## Optimization profiles
An optimization profile contains predetermined configuration settings that help you optimize a PDF document for a specific use.
The Pdftools SDK offers four optimization profiles:
- **[Web](#web-optimization-profile)**: Compress the file without affecting viewing quality on digital devices
- Removes redundant and unnecessary data for electronic document exchange
- Downsamples, clips, and intelligently compresses images
- Merges and subsets fonts
- Converts colors to RGB
- **[Archive](#archive-optimization-profile)**: Prepare a document for archiving in PDF/A format
- Removes redundant and unnecessary data for archiving
- Intelligently compresses images
- Merges and subsets fonts
- **[Print](#print-optimization-profile)**: Compress the file without affecting print quality
- Removes redundant and unnecessary data for printing
- Downsamples, clips, and intelligently compresses images
- Merges and subsets fonts
- Converts colors to CMYK
- **[Minimal file size](#minimal-file-size-optimization-profile)**: Remove redundant data and reduce image resolution to achieve a minimal viable file size
- Downsamples images
- Converts Type1 fonts to Type1C
- Removes metadata and output intents
- **[Mixed Raster Content (MRC)](#mixed-raster-content-optimization-profile)**: Apply Mixed Raster Content (MRC) optimization intended for compressing scanned PDF files containing large amounts of text. The MRC can include:
- Splitting documents into foreground, background, and mask layers
- Heavily downsampling and compressing foreground and background layers
- Lossless compression of mask layers
- Merging and subseting fonts
## Web optimization profile
All documents related to the web should be kept small in file size. As a consequence, they take less storage on the web server and can be transferred quicker, resulting in shorter download times.
To reduce the file size as much as possible, all information that is not required for displaying the document without a visual loss can be removed.
This may include:
- Downsampling images
- Clipping images to their visible parts
- Applying compressions algorithms with high compression ratios
- Collapsing redundant objects
- Removing unused resources
- Removing irrelevant information such as article threads, metadata, alternate images, document structure information, etc.
- Merging and sub-setting embedded font programs
With the Web optimization profile, images above 210 DPI are down-sampled and recompressed to 150 DPI. This leads to smaller output files.
When an image is recompressed, the `Balanced` strategy is used; however, this can be overridden through `ImageRecompressionOptions`.
Depending on the PDF documents to be optimized, font programs of embedded standard fonts can even be removed.
Additionally, PDF documents can be linearized. A PDF file is prepared so that pages can be accessed randomly via a PDF viewer web browser plugin, i.e. selected pages can be displayed before the whole file is downloaded. For this to work, the PDF viewer web browser plugin has to support correct interpretation of linearized PDF.
Documents that are intended to be displayed on a display should be saved in RGB (red green blue) color space. RGB is the native form for any light-emitting device, such as computer monitor or television. An RGB image uses three channels, and therefore takes up less space than a CMYK (cyan magenta yellow black) image, which uses four channels. With the Web optimization profile, all colors are converted to RGB.
:::important
With the **Web** optimization profile, the output PDF version is updated to PDF 1.7 or higher and PDF/A conformance is removed.
:::
## Print optimization profile
For printing applications, the file size is not the highest priority. It is more important to have a document that prints predictably. This means that correct fonts should be used, colors should look as expected, and images should be high in resolution.
For that reason, data from the original document that is used for a well-defined reproduction should not be removed or altered.
Embedded fonts should not be removed, images should not be downsampled, with exceptions.
For many printing applications, it may be beneficial to convert images to the CMYK color space because this is primarily used in systems that reflect light (such as printed paper).
With the **Print** optimization profile, all colors are converted to CMYK for optimal output on printing devices.
In certain documents, the same font is embedded multiple times. For example, if a PDF-producing software embeds the same font for each created page, then large multi-page documents may contain many copies of a font program.
Also, a document can contain a complete font program of which only very few glyphs are used for display.
In such situations, merging and sub-setting font programs can lead to faster printing.
Embedded Type1 (PostScript) fonts are converted to Type1C (Compact Font Format), which further reduces the file size.
There are still further ways to decrease the file size:
- Clipping images to their visible parts
- Compressing uncompressed images, e.g. with a lossless compression type
- Collapsing redundant objects
- Removing unused resources
- Removing irrelevant information for printing such as thumbnails, article threads, document structure information, etc.
With this profile, spider (web capture) information is removed.
The resolution of images is not modified.
When an image is recompressed, the `PreserveQuality` strategy is used; this can be overridden through the property `ImageRecompressionOptions`.
:::important
With the **Print** profile, the output PDF version is updated to PDF 1.7 or higher and PDF/A conformance is removed.
:::
## Archive optimization profile
For archiving, the priority is to preserve PDF/A conformance, maintaining document fidelity and reproducibility over time.
Only minimal document modification is performed.
This may include:
- Removing alternative images
- Removing thumbnails
- Collapsing redundant objects
- Removing unused resources
The resolution and color space of images must remain untouched.
When an image is recompressed, the `PreserveQuality` strategy is used to ensure the image keeps as high a quality as possible compared to the original; however, it can be overridden through the property `ImageRecompressionOptions`.
ALl content objects such as annotations, form fields, and links are copied with the **Archiving** profile.
Article threads, metadata, piece-info dictionaries, and the structure tree are not removed.
Signature appearances are flattened.
:::important
For PDF/A conforming input files, the PDF/A conformance is preserved if possible. For other files, the PDF version is updated to PDF 1.7 or higher.
:::
## Minimal file size optimization profile
In most cases, the focus in PDF optimization to decrease the file size.
This can be achieved by:
- Compressing images with an appropriate compression algorithm for lower image quality
- Collapsing redundant objects
- Removing unused resources
- Removing irrelevant information for printing such as thumbnails, article threads, document structure information, piece-info dictionaries, etc.
- Remove output intents
With the `MinimalFileSize` conversion profile, the output file size is further reduced by converting Embedded Type1 (PostScript) fonts to Type1C (Compact Font Format).
Metadata and spider (web capture) information are removed.
Output intents provide a means for matching the color characteristics of PDF page content with those of a target output device or production environment in which the document is printed.
Output intents are removed with the **minimal file size** optimization profile.
Images above 182 DPI are downsampled and recompressed to 130 DPI.
This leads to smaller output files.
When an image is recompressed, the `Balanced` strategy is used; this can be overridden through the property `ImageRecompressionOptions`.
## Mixed raster content optimization profile
PDF files with scanned content can have a very large file size due to the high resolution of the images stored in scanned PDF files. Minimizing the image size while maintaining text readability is important for workflows involving scanned text documents.
The Mixed Raster Content (MRC) algorithm minimizes the image size while maintaining text readability. The MRC divides scanned documents into foreground, background, and mask layers, storing the textual information in the mask layer using a lossless compression type. The MRC heavily down-samples and compresses foreground and background layers. The file size is further reduced by removing redundant objects, optimizing resources, merging and subsetting embedded fonts.
:::important
With the **Minimal file size** profile, the output PDF version is updated to PDF 1.7 or higher and PDF/A conformance is removed.
:::
{/* TODO Include comparison table with options true/false & profile*/}
---
## Compress and optimize a PDF document
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
The Pdftools SDK lets you compress and optimize a PDF document for a specific purpose.
Depending on the specified purpose, different operations are performed on the PDF document, such as reducing image resolution or removing unnecessary objects.
You can encrypt the output PDF as part of the optimization process.
:::tip Quick start with a code sample
Download the full sample now in **[C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/OptimizerSimple/Download?technology=C)**, **[C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/OptimizerSimple/Download?technology=CS)**, **[Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/OptimizerSimple/Download?technology=Java)**, **[Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/OptimizerSimple/Download?technology=Python)**, and **[Visual Basic](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/OptimizerSimple/Download?technology=VB)**.
Interested in Go, Rust or other programming language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.
:::
The Pdftools SDK currently supports five [optimization profiles](optimization-profiles.mdx) that are intended for the following purposes:
- **Archive:** Prepare a document for archiving in PDF/A format, reducing the file size prior to converting to PDF/A.
- **Minimal file size:** Remove redundant data and reduce image resolution to achieve a minimal viable file size.
- **Print:** Compress the file, but ensure that the print quality of the document is not affected.
- **Web:** Similar to the Print profile, but ensure that the viewing quality of the document is not affected when viewing on digital devices (e.g., in a web browser).
- **Mixed raster content:** Apply Mixed Raster Content (MRC) optimization intended for compressing scanned documents that contain large amounts of text.
**Steps to optimize a document**:
1. [Reading the input document](#reading-the-input-document)
2. [Creating an Optimizer object](#creating-an-optimizer-object)
3. [Setting an optimization profile](#setting-an-optimization-profile)
4. [Running the OptimizeDocument method](#running-the-optimizedocument-method)
5. [Full example](#full-example)
---
:::note Before you begin
You need to **[initialize the library](/docs/licenses/products/pdf-tools-sdk-license/#activate-the-pdftools-sdk-license)**.
:::
## Reading the input document
First you need to read the PDF document you want to validate. To do this, load the input document from the file system into a read-only input `Document`.
This `Document` can then later be passed to the `Converter`.
```csharp
// Open image document
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);
```
```java
// Open input document
FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
com.pdftools.pdf.Document inDoc = com.pdftools.pdf.Document.open(inStr);
```
## Creating an Optimizer object
You start the document optimization process by creating an `Optimizer` object.
The `Optimizer` object takes an input PDF document and optimizes the content for a specific purpose.
It then outputs the result to a document object that can be persisted to a file or used as an input for further processing.
```csharp
// Create the Optimizer object.
Optimizer optimizer = new Optimizer();
```
```java
// Create the Optimizer object.
Optimizer optimizer = new Optimizer();
```
## Setting an optimization profile
The `Profile` object controls the behavior of the `Optimizer` object during the optimization process.
The [profile](optimization-profiles.mdx) can be set to one of four subclasses that are used for different purposes: `Archive`, `MinimalFileSize`, `Print`, and `Web`.
This example uses the `Web` profile.
```csharp
// Create a profile that controls the Optimizer output behavior.
// The Web profile is used to optimize documents for electronic document exchange.
var profile = new Profiles.Web(); // Archive, MinimalFileSize, Print, Web
// Optionally, the profile's parameters can be changed according to the
// requirements of your optimization process
```
```java
// Create the profile that defines the optimization parameters.
// The Web profile is used to optimize documents for electronic document exchange.
Web profile = new Web(); // Archive, MinimalFileSize, Print, Web
// Optionally, the profile's parameters can be changed according to the
// requirements of your optimization process
```
## Running the OptimizeDocument method
After creating the `Optimize` and `Profile` objects, the final step is to call the `OptimizeDocument` method.
The document produced by this method has the optimizations applied to it that are defined by the optimization profile.
If the output document cannot be created, a detailed error message is generated.
```csharp
// Create the output stream.
using var outStr = File.Create(outPath);
// Optimize the document and save it to a file.
using var outDoc = optimizer.OptimizeDocument(inDoc, outStr, profile);
```
```java
// Create output stream
FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW);
// Optimize the document
Document outDoc = optimizer.optimizeDocument(inDoc, outStr, profile));
```
:::tip
During the optimization process, the output file may be encrypted and may be assigned permissions.
For more information on how PDF documents are encrypted, see [Encryption in PDF documents](../sign-and-secure/secure/pdf-encryption.mdx).
:::
## Full example
{/*sample source: PdfToolsSDK/Samples/Templates/optimizersimple.cs*/}
```csharp
// Open the PDF document to validate
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);
// Create the Optimizer object.
Optimizer optimizer = new Optimizer();
// Create a profile that controls the Optimizer output behavior.
// The Web profile is used to optimize documents for electronic document exchange.
var profile = new Profiles.Web();
// Create the output stream.
using var outStr = File.Create(outPath);
// Optimize the document and save it to a file.
using var outDoc = optimizer.OptimizeDocument(inDoc, outStr, profile);
```
{/*sample source: PdfToolsSDK/Samples/Templates/optimizersimple.java*/}
```java
// Create the Optimizer object.
Optimizer optimizer = new Optimizer();
// Create the profile that defines the optimization parameters.
// The Web profile is used to optimize documents for electronic document exchange.
Web profile = new Web();
// Optionally, the profile's parameters can be changed according to the
// requirements of your optimization process.
try (
// Open input document
FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
Document inDoc = Document.open(inStr);
// Create output stream
FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW);
// Optimize the document
Document outDoc = optimizer.optimizeDocument(inDoc, outStr, profile))
{
}
```
---
## Release notes
Learn about the latest updates of:
- [Pdftools SDK](#pdftools-sdk)
- [Toolbox add-on](#toolbox-add-on)
- [Pdftools SDK Shell Tool](#pdftools-sdk-shell-tool)
## Pdftools SDK
### Version 1.14.0
29 October 2025
#### Added
- Enhanced logging configuration environment variables:
- `PDFT_LOG_OUTPUT` for output control, replacing `PDF_TRACE_OUTPUT`. The `PDF_TRACE_OUTPUT` also remains supported for backward compatibility.
- `PDFT_LOG` for log level filters. The comma-separated format: `*:error,libbase:info`, where `*` sets the default level.
#### Changed
- Switched from the zlib to zlib-ng library, significantly improving performance when compressing and decompressing Flate streams by using SIMD instructions.
#### Fixed
- Corrected conformance retrieval logic in the `GetConformance` method to properly handle invalid `ConversionOptions` values.
- Certificate loading on Windows now includes Local Machine store in addition to Current User store, resolving certificate access issues for Internet Information Services (IIS) applications running under service accounts.
- Widget annotation appearance generation now correctly checks for rich text value (RV) entry instead of rich text style (DS) entry when determining whether to create appearance streams.
### Version 1.13.1
16 September 2025
#### Fixed
- Resolved an issue using an uninitialized variable that could cause unpredictable behavior during PNG processing.
- Fixed a stack buffer overflow when creating annotation appearances.
- Corrected glyph position problems caused by improper handling of adjustment values.
- Ensured the `GTS_PDFX` output intent is correctly copied into the output document to maintain PDF/X compliance. The `GTS_PDFX` defines the standardized printing output intent for PDF/X files.
- Fixed an infinite loop that could occur during optimization for specific malformed PDF files.
- Addressed an access violation related to cross-reference (xref) tables, preventing potential crashes.
### Version 1.13.0
29 July 2025
#### Added
- Added `IsFullRevisionCovered` flag to signature validation results to detect partial `ByteRanges`.
#### Changed
- Removed library load/unload messages from Python bindings.
#### Fixed
- Font name decoding for Type0 fonts on Linux and macOS to preserve Unicode characters.
- Malformed import in `native_base.py` that caused errors in Python bindings.
- Fixed error reporting for non-UTF8 colorant name on Linux and macOS.
- Font name decoding on Linux and macOS to align behavior with Windows.
- Fixed unexpected termination when processing image dictionaries with an empty `/Filter` array.
- Removed stray null terminators from strings returned by the Python interface.
### Version 1.12.0
19 June 2025
#### Added
- Pdftools SDK now natively supports Linux ARM64 processor architecture.
#### Fixed
- Previously, soft mask dimensions were not properly validated when a matte background was present.
### Version 1.11.1
26 May 2025
#### Fixed
- Resolved an issue that could cause a crash during rendering of Type 1 shadings.
- Addressed a problem with native library shutdown procedures that led to crashes or hangs when used through language bindings.
- Corrected the internal mapping for the `WordSeparationFactor` option, which previously could result in incorrect text extraction configuration.
### Version 1.11.0
16 May 2025
#### Added
- Improved multi-threaded handling of shared read-only data structures, allowing read-only configuration data to be shared safely between threads.
#### Fixed
- Resolved a crash that occurred when merging PDF files containing form fields without appearance streams while flattening was enabled.
### Version 1.10.0
12 May 2025
#### Added
- As of this update, you can now extract text from PDFs by using the Pdftools SDK. Review the following API references for more information: [C](https://api-reference.pdf-tools.com/pdfsdk/1.10/cdoc/_pdf_tools___pdf_tools_extraction_8h.html), [Java](https://api-reference.pdf-tools.com/pdfsdk/1.10/javadoc/com/pdftools/extraction/package-summary.html), [.NET](https://api-reference.pdf-tools.com/pdfsdk/1.10/dotnet/html/N_PdfTools_Extraction.htm), and [Python](https://api-reference.pdf-tools.com/pdfsdk/1.10/pydocs/_autosummary/pdftools_sdk.extraction.html#module-pdftools_sdk.extraction).
- Code samples now include links to Jupyter notebooks marked as the **Open in colab** buttons. Review the following code samples:
- [Pdftools SDK code samples](./code-samples/pdftools-sdk-samples.mdx)
- [Toolbox add-on code samples](./code-samples/pdftools-sdk-toolbox-samples.mdx)
### Version 1.9.1
14 April 2025
#### Added
- With this release, we are launching a new [Python Jupyter notebooks repository](https://github.com/pdf-tools/components-code-sample-hub) demonstrating the core functionality of the Pdftools SDK, including step-by-step examples for key features and use cases.
#### Fixed
- Previously, rendering PDFs with the wrong alternate colorspaces could cause the Pdftools SDK to crash. With this update, the rendering engine now falls back to CMYK rendering if the alternate color transform cannot be created, preventing the crash.
- Prior to this update, a crash occurred when IIS processes terminated, causing the Pdftools SDK DLL to unload without properly releasing its resources. With this release, the issue has been resolved, allowing the DLL to safely unload even when shutdown hooks fail to execute as expected.
- Previously, document timestamps (ETSI.RFC3161) were not recognized if the PDF lacked an explicit declaration of the correct signature type. This update ensures that timestamps are correctly validated as long as the signature itself is valid and the signed content remains intact.
### Version 1.9.0
14 March 2025
#### Added
- Improved support for HEIC files.
#### Fixed
- Previously, under certain circumstances, a regression caused the decryption of encrypted PDFs to fail. The issue is fixed with this release.
- Fixed a bug that caused crashes when handling JPEG images with the Pdftools SDK on 32-bit Windows systems.
- Improved handling of faulty PostScript string syntax to ensure correct parsing of ToUnicode maps.
### Version 1.8.0
20 January 2025
#### Added
- Pdftools SDK now natively supports Microsoft Windows ARM64 processor architecture.
- During PDF/A conversion, you can now add embed associated files using the [AddAssociatedFile](https://api-reference.pdf-tools.com/pdfsdk/1.8/dotnet/html/M_PdfTools_PdfA_Conversion_Converter_AddAssociatedFile.htm) method.
- Test whether any update leading to a specific revision does not contain a digital signature using the new [HasNonSigningUpdates](https://api-reference.pdf-tools.com/pdfsdk/1.8/dotnet/html/P_PdfTools_Pdf_Revision_HasNonSigningUpdates.htm) property.
- Suppress rendering of text when converting a PDF to an image using the new [RenderText](https://api-reference.pdf-tools.com/pdfsdk/1.8/dotnet/html/P_PdfTools_Pdf2Image_ContentOptions_RenderText.htm) property.
- With this update, you can force an image to fill the page (respecting the image's aspect ratio) using the [ForceFit](https://api-reference.pdf-tools.com/pdfsdk/1.8/dotnet/html/P_PdfTools_Image2Pdf_ShrinkToFit_ForceFit.htm) property.
- With this update, the Pdftools SDK introduces a new Pythonic, object-oriented interface with structured classes, native Python types for data handling, and enhanced error management through exceptions. For more details on how to try the new Pythonic interface, review the [Python getting started guide](./getting-started/pdftools-sdk/pdftools-sdk-python.mdx).
#### Fixed
- Missing `firstChar` or `lastChar` entries in damaged font dictionaries are restored when enough information is available.
- Fixed issue for PDFs with signed signature fields without any appearance.
- There was an issue when the SDK tried to get resources by HTTPS in the visual appearance of JSON or XML configuration files. The issue was fixed with this update.
### Version 1.7.0
28 June 2024
#### Added
- The Pdftools SDK now lets you adjust the image quality using the [ImageQuality](https://api-reference.pdf-tools.com/pdfsdk/1.7/dotnet/html/P_PdfTools_PdfA_Conversion_ConversionOptions_ImageQuality.htm) property when converting a PDF file to PDF/A. This setting is used when images must be recompressed during the conversion process.
- You can now use **pip** package manager to install the Pdftools SDK. Use `pip install https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSDK/latest/pdftools_sdk-latest.tar.gz` to install the Python version of the Pdftools SDK from our servers.
#### Fixed
- Corrected an issue where Unicode characters were sometimes converted incorrectly when using the [Python version of the Pdftools SDK](https://www.pdf-tools.com/docs/pdf-tools-sdk/getting-started/pdftools-sdk/pdftools-sdk-python/).
- Fixed a bug where some ZUGFeRD v3 invoice XML files were not correctly recognized by the [AddInvoiceXml](https://api-reference.pdf-tools.com/pdfsdk/1.7/dotnet/html/M_PdfTools_PdfA_Conversion_Converter_AddInvoiceXml.htm) method when creating a ZUGFeRD invoice.
### Version 1.6.0
31 May 2024
#### Added
- You can now create a fully compliant ZUGFeRD or Factur-X invoice using the Pdftools SDK. To do this you [add the invoice XML file](https://api-reference.pdf-tools.com/pdfsdk/1.6/dotnet/html/M_PdfTools_PdfA_Conversion_Converter_AddInvoiceXml.htm) before calling the [Convert](https://api-reference.pdf-tools.com/pdfsdk/1.6/dotnet/html/M_PdfTools_PdfA_Conversion_Converter_Convert.htm) method.
- It is now possible to [rotate a page](https://api-reference.pdf-tools.com/pdfsdk/1.6/dotnet/html/P_PdfTools_DocumentAssembly_PageCopyOptions_PageRotation.htm) when merging pages of PDF documents using the [Assemble](https://api-reference.pdf-tools.com/pdfsdk/1.6/dotnet/html/T_PdfTools_DocumentAssembly_DocumentAssembler.htm) method.
- Instead of using the default [Font directories](./api-references/technical-notes/general-notes.mdx#font-directories), you can now also add a custom font directory using the [AddFontDirectory](https://api-reference.pdf-tools.com/pdfsdk/1.6/dotnet/html/M_PdfTools_Sdk_AddFontDirectory.htm) method.
#### Fixed
- Previously, a default value was always used for the PDF Producer value. With this update, the issue was fixed, and the PDF Producer value is now set correctly using the `producerSuffix`
parameter of the [`Initialize(licenseKey, producerSuffix)`](https://api-reference.pdf-tools.com/pdfsdk/1.6/dotnet/html/M_PdfTools_Sdk_Initialize.htm) method.
- The validation of a digital signature's [Appearance](https://api-reference.pdf-tools.com/pdfsdk/1.6/dotnet/html/Properties_T_PdfTools_Sign_Appearance.htm) has been improved, to prevent inconsistent boundary values.
### Version 1.5.0
17 April 2024
#### Added
- You can now apply [Mixed Raster Content (MRC)](https://api-reference.pdf-tools.com/pdfsdk/1.5/dotnet/html/T_PdfTools_Optimization_Profiles_Mrc.htm) optimization to a PDF document using the [Optimize](optimize/optimize-a-pdf.mdx) feature of the Pdftools SDK. MRC optimization is intended for compressing scanned PDF files that contain large amounts of text.
- It is now possible to set the values for [ThresholdDPI](https://api-reference.pdf-tools.com/pdfsdk/1.5/dotnet/html/P_PdfTools_Optimization_Profiles_Web_ThresholdDPI.htm) and [ReduceColorComplexity](https://api-reference.pdf-tools.com/pdfsdk/1.5/dotnet/html/P_PdfTools_Optimization_ImageRecompressionOptions_ReduceColorComplexity.htm) when optimizing PDF files. This addition gives you more control over how images in the document are resampled and compressed.
#### Changed
- The [OptimizeDocument](https://api-reference.pdf-tools.com/pdfsdk/1.5/dotnet/html/M_PdfTools_Optimization_Optimizer_OptimizeDocument.htm) method of the PDF optimizer will now attempt to apply lossless compression for images with bitonal (Group4 or JBIG2 compression) and indexed (Flate or LZW compression) color spaces.
### Version 1.4.0
5 March 2024
#### Added
- Before this update, only the common name (CN) of a signing certificate could be retrieved. With this update, you can get the full [distinguished name](https://api-reference.pdf-tools.com/pdfsdk/1.4/dotnet/html/P_PdfTools_SignatureValidation_Certificate_Subject.htm) (DN) of a signing certificate. The DN format is RFC 4514. The DN includes the legal name, country, and other information about the person or authority who owns the certificate.
- Before this update, you could only read and write to file streams with the C API. As of this update, you can also use [memory streams](https://api-reference.pdf-tools.com/pdfsdk/1.4/cdoc/_pdf_tools___pdf_tools_sys_8h.html#add0ac122cf14ff02342a4f2b13fdcd5a) with the C API.
### Version 1.3.0
13 October 2023
#### Added
- [DocumentAssembler](https://api-reference.pdf-tools.com/pdfsdk/1.3/dotnet/html/T_PdfTools_DocumentAssembly_DocumentAssembler.htm) class. This class allows you to combine multiple input PDF documents into one output document, or split one input PDF document into multiple output documents.
- You can now include a customizable signature appearance when [Signing a PDF document](sign-and-secure/sign/sign-document.mdx). A signature's appearance may be any combination of text, images, and other PDF documents.
- **Linux**: Added new distribution for older Linux systems (glibc 2.12+).
#### Changed
- Before version 1.3.3 you needed to use an evaluation license key to try the Pdftools SDK. With version 1.3.3, you can use the Pdftools SDK without a license key with watermarked output files. As a result, you can try the Pdftools SDK without any license key. To remove the watermark from the output files, contact the Pdftools sales team through the [Contact page](https://www.pdf-tools.com/contact/) to get a full license.
### Version 1.2.0
25 August 2023
- Added the [MetadataSettings](https://api-reference.pdf-tools.com/pdfsdk/1.2/dotnet/html/T_PdfTools_Pdf_MetadataSettings.htm) class. This class allows you to set Metadata in the output PDF document, by providing them in the producer method's [OutputOptions](https://api-reference.pdf-tools.com/pdfsdk/1.2/dotnet/html/T_PdfTools_Pdf_OutputOptions.htm).
#### Changed
- **Linux**: The minimum required glibc version was upgraded from 2.27 to 2.34.
### Version 1.1.0
31 May 2023
#### Added
- Signature validation for the [digital signing](sign-and-secure/sign/README.mdx) functionality. This allows you to extract signing certificate information and trust chain information, and perform validation of time-stamps, handle expired certificates, use custom trust stores, and check for the latest document revision.
#### Changed
- **Updated C API ZIP archive layout**: The C API ZIP archive directory layout has been updated.
- **Updated Java API ZIP archive layout**: The Java API ZIP archive directory layout has been updated.
## Toolbox add-on
### Version 1.11.0
29 October 2025
#### Added
- Added `ContentGenerator.TagAsArtifact` method, which lets you tag all content created after its call as an artifact. For more information, review the API references: [C](https://api-reference.pdf-tools.com/pdfsdkxt/1.11/cdoc/_pdf_tools___toolbox___ptx_pdf_content_8h.html#a197194d012812cbc5791ebd524dc3696), [Java](https://api-reference.pdf-tools.com/pdfsdkxt/1.11/javadoc/com/pdftools/toolbox/pdf/content/ContentGenerator.html#tagAsArtifact(com.pdftools.toolbox.pdf.content.ArtifactType)), [.NET](https://api-reference.pdf-tools.com/pdfsdkxt/1.11/dotnet/html/M_PdfTools_Toolbox_Pdf_Content_ContentGenerator_TagAsArtifact.htm), [Python](https://api-reference.pdf-tools.com/pdfsdkxt/1.11/pydocs/_autosummary/pdftools_toolbox.pdf.content.content_generator.html#pdftools_toolbox.pdf.content.content_generator.ContentGenerator.tag_as_artifact).
- Enhanced logging configuration environment variables:
- `PDFT_LOG_OUTPUT` for output control, replacing `PDF_TRACE_OUTPUT`. The `PDF_TRACE_OUTPUT` also remains supported for backward compatibility.
- `PDFT_LOG` for log level filters. The comma-separated format: `*:error,libbase:info`, where `*` sets the default level.
#### Changed
- Switched from the zlib to zlib-ng library, significantly improving performance when compressing and decompressing Flate streams by using SIMD instructions.
#### Fixed
- Gray color space output intent is now set correctly.
- Widget annotation appearance generation now correctly checks for rich text value (RV) entry instead of rich text style (DS) entry when determining whether to create appearance streams.
### Version 1.10.0
16 September 2025
#### Added
- As of this release, you can now expose raw strings of text elements as arrays of bytes. As a result, the developers who use the Toolbox add-on can work directly with the underlying encoded text data for advanced processing and custom workflows. For more information, review the following API references: [C](https://api-reference.pdf-tools.com/pdfsdkxt/1.10/cdoc/_pdf_tools___toolbox___ptx_pdf_content_8h.html#aa4353fe4477ffe98b8ea261e64121d85), [.NET](https://api-reference.pdf-tools.com/pdfsdkxt/1.10/dotnet/html/P_PdfTools_Toolbox_Pdf_Content_TextFragment_RawString.htm), [Java](https://api-reference.pdf-tools.com/pdfsdkxt/1.10/javadoc/com/pdftools/toolbox/pdf/content/TextFragment.html#getRawString()), [Python](https://api-reference.pdf-tools.com/pdfsdkxt/1.10/pydocs/_autosummary/pdftools_toolbox.pdf.content.text_fragment.html#pdftools_toolbox.pdf.content.text_fragment.TextFragment.raw_string).
- Introduced a new method for retrieving the resolution of image masks. Find more details in the API references: [C](https://api-reference.pdf-tools.com/pdfsdkxt/latest/cdoc/_pdf_tools___toolbox___ptx_pdf_content_8h.html#a38e3da6daeef207ff478c34fed2fa5c6), [.NET](https://api-reference.pdf-tools.com/pdfsdkxt/latest/dotnet/html/M_PdfTools_Toolbox_Pdf_Content_ImageMask_GetResolution.htm), [Java](https://api-reference.pdf-tools.com/pdfsdkxt/1.10/javadoc/com/pdftools/toolbox/pdf/content/ImageMask.html#getResolution(com.pdftools.toolbox.geometry.real.AffineTransform)), [Python](https://api-reference.pdf-tools.com/pdfsdkxt/latest/pydocs/_autosummary/pdftools_toolbox.pdf.content.image_mask.html#pdftools_toolbox.pdf.content.image_mask.ImageMask.get_resolution).
#### Fixed
- Resolved an issue using an uninitialized variable that could cause unpredictable behavior during PNG processing.
- Fixed a stack buffer overflow when creating annotation appearances.
- Corrected glyph position problems caused by improper handling of adjustment values.
- Ensured the `GTS_PDFX` output intent is correctly copied into the output document to maintain PDF/X compliance. The `GTS_PDFX` defines the standardized printing output intent for PDF/X files.
- Fixed an infinite loop that could occur during optimization for specific malformed PDF files.
- Addressed an access violation related to cross-reference (xref) tables, preventing potential crashes.
### Version 1.9.0
29 July 2025
#### Added
- Completed basic PDF/Universal Accessibility (PDF/UA) functionality:
- Enabled reading of existing logical structure through `Pdf.Structure` API.
- Added getter and setter methods for logical structure attributes: `AltT`,`ActualT`, `E`, and `Lang`
- Extended the API declaring PDF/UA compliance by setting the `Marked` flag and embedding the `pdfuaid` in XMP metadata.
- Added developer guides for accessing and creating logical structure in PDF documents. For more information, review [Accessibility](./toolbox/accessibility/README.mdx) section with three guides: [Create an accessible PDF from scratch](./toolbox/accessibility/create-accessible-pdf.mdx), [Add logical structure to an existing PDF](./toolbox/accessibility/add-logical-structure-to-existing-pdf.mdx), and [Read PDF logical structure](./toolbox/accessibility/read-logical-structure.mdx)
- Added samples for creating accessible PDF/UA with logical structure, reading logical structure from tagged PDF documents, and adding logical structure during PDF remediation.
#### Changed
- Removed library load and unload messages from Python bindings.
- Replaced misleading `ArgumentException` with `CorruptException` for incorrect AF entry in PDF catalog.
#### Fixed
- Font name decoding for Type0 fonts on Linux and macOS to preserve Unicode characters.
- Malformed import in native\_base.py that caused errors in Python bindings.
- Fixed blank pages caused by incorrect indirect color space references in inline images.
- Fixed unexpected termination when processing image dictionaries with an empty `/Filter` array.
- Fixed text coordinate errors caused by specific usage of `q` and `Q` operators.
- Fixed error reporting for non-UTF8 colorant name on Linux and macOS.
- Font name decoding on Linux and macOS to align behavior with Windows.
- Removed stray null terminators from strings returned by the Python interface.
### Version 1.8.0
19 June 2025
#### Added
- The Toolbox add-on now natively supports Linux ARM64 processor architecture.
- `GetResolution` method was added to the `Image` class. For more information, review the API references: [C](https://api-reference.pdf-tools.com/pdfsdkxt/1.8/cdoc/_pdf_tools___toolbox___ptx_pdf_content_8h.html#a30e928adb41205117fa1827e2a5dc773), [Java](https://api-reference.pdf-tools.com/pdfsdkxt/1.8/javadoc/com/pdftools/toolbox/pdf/content/Image.html#getResolution(com.pdftools.toolbox.geometry.real.AffineTransform)), [.NET](https://api-reference.pdf-tools.com/pdfsdkxt/1.8/dotnet/html/M_PdfTools_Toolbox_Pdf_Content_Image_GetResolution.htm), [Python](https://api-reference.pdf-tools.com/pdfsdkxt/1.8/pydocs/_autosummary/pdftools_toolbox.pdf.content.image.html#pdftools_toolbox.pdf.content.image.Image.get_resolution).
- To support advanced cryptographic processing, the `SignatureField` class in the `PdfTools.Toolbox.Pdf` API now exposes the raw digital signature blob through a new read-only property `SignatureContents`. This property returns the exact binary value of the `/Contents` key from the PDF signature dictionary—equivalent to what was previously accessible through `Secure.GetSignature` in the legacy PDF Toolbox SDK. For more information, review the API references: [C](https://api-reference.pdf-tools.com/pdfsdkxt/1.8/cdoc/_pdf_tools___toolbox___ptx_pdf_forms_8h.html#a5e92f70104b47a44551e6531d62fa508), [Java](https://api-reference.pdf-tools.com/pdfsdkxt/1.8/javadoc/com/pdftools/toolbox/pdf/forms/SignedSignatureField.html#getSignatureContents()), [.NET](https://api-reference.pdf-tools.com/pdfsdkxt/1.8/dotnet/html/P_PdfTools_Toolbox_Pdf_Forms_SignedSignatureField_SignatureContents.htm), [Python](https://api-reference.pdf-tools.com/pdfsdkxt/1.8/pydocs/_autosummary/pdftools_toolbox.pdf.content.image.html#pdftools_toolbox.pdf.content.image.Image.get_resolution).
#### Fixed
- Previously, soft mask dimensions were not properly validated when a matte background was present.
- Fixed PDF corruption and blank pages that occurred when cloning documents with certain image color spaces.
### Version 1.7.1
26 May 2025
#### Fixed
- Resolved an issue where the `ContentExtractor` class reported incorrect glyph widths.
- Addressed a problem with native library shutdown procedures that led to crashes or hangs when used through language bindings.
### Version 1.7.0
16 May 2025
#### Added
- Improved multi-threaded handling of shared read-only data structures, allowing read-only configuration data to be shared safely between threads.
### Version 1.6.1
14 April 2025
#### Added
- With this release, we are launching a new [Python Jupyter notebooks repository](https://github.com/pdf-tools/components-code-sample-hub) demonstrating the core functionality of the Toolbox add-on, including step-by-step examples for key features and use cases.
#### Fixed
- Previously, a crash occurred when IIS processes terminated, causing the Toolbox add-on DLL to unload without properly releasing its resources. This issue has been resolved, allowing the DLL to safely unload even when shutdown hooks fail to execute as expected.
- Previously, PDFs utilizing Type 3 fonts appeared visually distorted after copying elements using `ContentElement.Copy`. This bug has been resolved, and the copied elements are now rendered correctly.
### Version 1.6.0
14 March 2025
#### Added
- Improved support for HEIC files.
#### Fixed
- Prior to this release, the image conversion functionality was not working in Python. As of this update, the underlying issue is fixed by using aliases for imports when needed. Aliases are also added to some built-in methods from providers to fix inconsistencies.
- Previously, radio buttons were improperly copied to the output documents.
- Previously, under certain circumstances, a regression caused the decryption of encrypted PDFs to fail. The issue is fixed with this release.
- Fixed a bug that caused crashes when handling JPEG images in the Toolbox add-on on 32-bit Windows system.
- Improved handling of faulty PostScript string syntax to ensure correct parsing of ToUnicode maps.
- The Python version of the content addition sample [Add data matrix to PDF](./code-samples/pdftools-sdk-toolbox-samples.mdx#add-data-matrix-to-pdf) now correctly places the matrix on the page.
- The Python code sample [Extract all text from PDF](./code-samples/pdftools-sdk-toolbox-samples.mdx#extract-all-text-from-pdf) now correctly reports page numbers when displaying extracted text to the console.
### Version 1.5.0
24 January 2025
#### Added
- The Toolbox add-on now natively supports Microsoft Windows ARM64 processor architecture.
- You can now copy a page without copying its graphical content using the new [DoNotCopyContent](https://api-reference.pdf-tools.com/pdfsdkxt/1.5/dotnet/html/P_PdfTools_Toolbox_Pdf_PageCopyOptions_DoNotCopyContent.htm) option. This is helpful for content removal workflows that have to fully preserve a page's metadata, annotations, and widgets.
#### Fixed
- A bug where the soft mask of an image was lost during copying has been fixed.
- This update fixes an issue where the Toolbox add-on incorrectly handled x-advance information of the text painting operator, leading to wrongly placed glyphs.
### Version 1.4.0
28 November 2024
#### Added
- You can now set the [Hidden](https://api-reference.pdf-tools.com/pdfsdkxt/1.4/dotnet/html/P_PdfTools_Toolbox_Pdf_Forms_Widget_Hidden.htm) flag for `Widget` classes. When this flag is set, the `Widget` is invisible and unavailable to user interaction.
- You can now get and set the [Locked](https://api-reference.pdf-tools.com/pdfsdkxt/1.4/dotnet/html/P_PdfTools_Toolbox_Pdf_Forms_Widget_Locked.htm) flag for `Widget` class. When a `Widget` class is `Locked` its properties can't be changed.
- As of this update, you can also get and set the `FontSize` for the [CombTextField](https://api-reference.pdf-tools.com/pdfsdkxt/1.4/dotnet/html/T_PdfTools_Toolbox_Pdf_Forms_CombTextField.htm) and the [ListBox](https://api-reference.pdf-tools.com/pdfsdkxt/1.4/dotnet/html/T_PdfTools_Toolbox_Pdf_Forms_ListBox.htm) classes.
### Version 1.3.0
9 October 2024
#### Added
- The [Pdf.Structure](https://api-reference.pdf-tools.com/pdfsdkxt/1.3/dotnet/html/N_PdfTools_Toolbox_Pdf_Structure.htm) namespace has been added to the Toolbox add-on. You can use the classes and methods in this namespace to add structure information ("tags") to the generated PDF content for use cases such as PDF accessibility. With this update, you can [Tag](https://api-reference.pdf-tools.com/pdfsdkxt/1.3/dotnet/html/M_PdfTools_Toolbox_Pdf_Content_ContentGenerator_TagAs.htm) content created using the [ContentGenerator](https://api-reference.pdf-tools.com/pdfsdkxt/1.3/dotnet/html/M_PdfTools_Toolbox_Pdf_Content_ContentGenerator_TagAs.htm) and link the content to the document's [Structure Tree](https://api-reference.pdf-tools.com/pdfsdkxt/1.3/dotnet/html/T_PdfTools_Toolbox_Pdf_Structure_Tree.htm). You can also create custom tags by adding them to the document's [RoleMap](https://api-reference.pdf-tools.com/pdfsdkxt/1.3/dotnet/html/T_PdfTools_Toolbox_Pdf_Structure_RoleMap.htm).
- As of this update, you can determine whether a font is embedded in a PDF by checking the [IsEmbedded](https://api-reference.pdf-tools.com/pdfsdkxt/1.3/dotnet/html/P_PdfTools_Toolbox_Pdf_Content_Font_IsEmbedded.htm) property of the [Font](https://api-reference.pdf-tools.com/pdfsdkxt/1.3/dotnet/html/T_PdfTools_Toolbox_Pdf_Content_Font.htm) object.
- You can now redact a rectangular area of an image using the [Redact](https://api-reference.pdf-tools.com/pdfsdkxt/1.3/dotnet/html/M_PdfTools_Toolbox_Pdf_Content_Image_Redact.htm) method of the [Image](https://api-reference.pdf-tools.com/pdfsdkxt/1.3/dotnet/html/T_PdfTools_Toolbox_Pdf_Content_Image.htm) class. This changes the content of the image so that all pixels within the defined rectangle are set to the same color.
#### Fixed
- With this update, you can set the URI for the [LicensingService](https://api-reference.pdf-tools.com/pdfsdkxt/1.3/dotnet/html/P_PdfTools_Toolbox_Sdk_LicensingService.htm) using the [Sdk](https://api-reference.pdf-tools.com/pdfsdkxt/1.3/dotnet/html/T_PdfTools_Toolbox_Sdk.htm) class of the Toolbox add-on. Before this fix, the default value for the LicensingService was always used.
- Before this update, the Toolbox add-on sometimes could terminate unexpectedly when:
- Iterating through the [Content](https://api-reference.pdf-tools.com/pdfsdkxt/1.3/dotnet/html/P_PdfTools_Toolbox_Pdf_Page_Content.htm) of a [Page](https://api-reference.pdf-tools.com/pdfsdkxt/1.3/dotnet/html/T_PdfTools_Toolbox_Pdf_Page.htm).
- Loading the [ExportName](https://api-reference.pdf-tools.com/pdfsdkxt/1.3/dotnet/html/P_PdfTools_Toolbox_Pdf_Forms_FieldNode_ExportName.htm) of a [FieldNode](https://api-reference.pdf-tools.com/pdfsdkxt/1.3/dotnet/html/T_PdfTools_Toolbox_Pdf_Forms_FieldNode.htm).
The underlying issues were fixed. As a result, the Toolbox add-on no longer crashes in the described scenarios.
### Version 1.2.0
22 July 2024
#### Added
- Image sampling accesses and handles the raw pixel data of an image in a sequential order without altering the resolution. This involves reading or setting the pixel values directly, often in the context of image processing or manipulation at the most detailed level. You can now get and set image samples using the Toolbox add-on. Review the [Image.Samples](https://api-reference.pdf-tools.com/pdfsdkxt/1.2/dotnet/html/P_PdfTools_Toolbox_Pdf_Content_Image_Samples.htm) property in the API documentation for more information.
- As of this update, you can set the URL for the [Licensing Service](https://api-reference.pdf-tools.com/pdfsdkxt/1.2/dotnet/html/P_PdfTools_Toolbox_Sdk_LicensingService.htm) using the [Sdk Class](https://api-reference.pdf-tools.com/pdfsdkxt/1.2/dotnet/html/T_PdfTools_Toolbox_Sdk.htm) of the Toolbox add-on. This URL is used for trial licenses and page-based licenses.
### Version 1.1.0
28 June 2024
#### Added
- It is now possible to retrieve information about a content element's Optional Content Membership using the Toolbox add-on for the Pdftools SDK. Optional Content Membership is defined by Optional Content Groups (also called layers) whose state determines whether a content element is visible or invisible.
- You can now retrieve the Rotation (`None`, `Clockwise`, `UpsideDown`, or `CounterClockwise`) of a page using the Toolbox add-on for the Pdftools SDK.
### Version 1.0.0
24 April 2024
#### Added
- Integrated the [Toolbox add-on](./getting-started/toolbox/README.mdx) into the Pdftools SDK. Now all the functionality from the PDF Toolbox SDK is included with your Pdftools SDK license.
## Pdftools SDK Shell Tool
### Version 1.10.0
29 October 2025
#### Added
- Enhanced logging configuration environment variables:
- `PDFT_LOG_OUTPUT` for output control, replacing `PDF_TRACE_OUTPUT`. The `PDF_TRACE_OUTPUT` also remains supported for backward compatibility.
- `PDFT_LOG` for log level filters. The comma-separated format: `*:error,libbase:info`, where `*` sets the default level.
#### Changed
- Switched from the zlib to zlib-ng library, significantly improving performance when compressing and decompressing Flate streams by using SIMD instructions.
#### Fixed
- Correct the usage text for the render-archive operation as there is no `-max` option in the general options.
- Corrected conformance retrieval logic in the `GetConformance` method to properly handle invalid `ConversionOptions` values.
- Certificate loading on Windows now includes Local Machine store in addition to Current User store, resolving certificate access issues for Internet Information Services (IIS) applications running under service accounts.
### Version 1.9.1
16 September 2025
#### Fixed
- Resolved an issue using an uninitialized variable that could cause unpredictable behavior during PNG processing.
- Fixed a stack buffer overflow when creating annotation appearances.
- Corrected glyph position problems caused by improper handling of adjustment values.
- Ensured the `GTS_PDFX` output intent is correctly copied into the output document to maintain PDF/X compliance. The `GTS_PDFX` defines the standardized printing output intent for PDF/X files.
- Fixed an infinite loop that could occur during optimization for specific malformed PDF files.
- Addressed an access violation related to cross-reference (xref) tables, preventing potential crashes.
### Version 1.9.0
29 July 2025
#### Fixed
- Fixed blank pages caused by incorrect indirect color space references in inline images.
- Fixed unexpected termination when handling image dictionaries with empty `/Filter` array.
### Version 1.8.0
19 June 2025
#### Added
- As of this update, text you can now extract text from PDFs using the following commands:
- `text-extract`: Recommended for LLM ingestion. Extracts text in the order it appears in the PDF.
- `layout-text-extract`: Extract text by mimicking the layout of the PDF.
- Pdftools SDK Shell Tool now natively supports Linux ARM64 processor architecture.
#### Fixed
- Previously, soft mask dimensions were not properly validated when a matte background was present.
- Corrected handling of the `fit` keyword in alternate text validation.
### Version 1.7.0
23 April 2025
#### Added
- Add the support to embedding files during a PDF/A conversion: embedding files can be associated to the converted PDF
- Add fit page option to the import image functionality: all images will be scaled to fit the page size (including enlarging smaller images).
- Improved support for HEIC files.
#### Fixed
- Fixed a bug that caused crashes when handling JPEG images with the Pdftools SDK on 32-bit Windows systems.
- Improved handling of faulty PostScript string syntax to ensure correct parsing of ToUnicode maps.
- Previously, document timestamps (ETSI.RFC3161) were not recognized if the PDF lacked an explicit declaration of the correct signature type. This update ensures that timestamps are correctly validated as long as the signature itself is valid and the signed content remains intact.
- Previously, rendering PDFs with the wrong alternate colorspaces could cause the Pdftools SDK to crash. With this update, the rendering engine now falls back to CMYK rendering if the alternate color transform cannot be created, preventing the crash.
- Previously, under certain circumstances, a regression caused the decryption of encrypted PDFs to fail. The issue is fixed with this release.
### Version 1.6.0
10 January 2025
#### Added
- Add a new method `AddAssociatedFile` that lets you to embed a file into a PDF. For more information, review the API references: [C](https://api-reference.pdf-tools.com/pdfsdk/1.10/cdoc/_pdf_tools___pdf_tools_pdf_a_conversion_8h.html#ab674762cd56eda03c2ed78332e94c343), [Java](https://api-reference.pdf-tools.com/pdfsdk/1.10/javadoc/com/pdftools/pdfa/conversion/Converter.html#addAssociatedFile(com.pdftools.sys.Stream,java.lang.String,java.lang.Integer,com.pdftools.pdfa.conversion.AFRelationship,java.lang.String,java.lang.String,java.time.OffsetDateTime)), [.NET](https://api-reference.pdf-tools.com/pdfsdk/1.10/dotnet/html/M_PdfTools_PdfA_Conversion_Converter_AddAssociatedFile.htm), [Python](https://api-reference.pdf-tools.com/pdfsdk/1.10/pydocs/_autosummary/pdftools_sdk.pdf_a.conversion.converter.html#pdftools_sdk.pdf_a.conversion.converter.Converter.add_associated_file).
- The Pdftools SDK Shell Tool now natively supports Microsoft Windows ARM64 processor architecture.
#### Fixed
- Add ability to get a license key from a default location when none is provided. The usage help message will display the alternative locations of the license (file or env. variable)
- Corrected encoding of console text output.
- Shell tool version couldn’t be fetched from the executable and properly display in usage help message.
- Missing firstChar or lastChar entries in damaged font dictionaries are restored when enough information is available.
- Fixed issue for PDFs with signed signature fields without any appearance.
- There was an issue when the SDK tried to get resources by HTTPS in the visual appearance of JSON or XML configuration files. The issue was fixed with this update.
- Fixed a bug where some ZUGFeRD v3 invoice XML files were not correctly recognized by the AddInvoiceXml method when creating a ZUGFeRD invoice.
### Version 1.5.0
28 June 2024
#### Added
- You can now pass an optional `-q ` parameter to the `convert` command in the Pdftools SDK Shell Tool, to set the image quality using the [ImageQuality](https://api-reference.pdf-tools.com/pdfsdk/1.7/dotnet/html/P_PdfTools_PdfA_Conversion_ConversionOptions_ImageQuality.htm) property when converting a PDF file to PDF/A. This setting is used when images must be recompressed during the PDF/A conversion process.
### Version 1.4.0
10 June 2024
#### Added
- Support for converting a PDF document and an XML file to a PDF/A invoice in ZUGFeRD or Factur-X format. You can now pass an optional `-xml ` parameter to the `convert` command of the Pdftools SDK Shell Tool to embed the specified XML file and create the invoice.
- You can now rotate a page when copying it from one PDF to another. Pass the optional `-rot ` parameter to the `merge` command to rotate a set of pages by the specified value (`90`, `180`, or `270` degrees) before adding them to the output file.
- Support for [digital signature](./sign-and-secure/sign/README.mdx) functionality using the Pdftools SDK Shell Tool. You can now sign, certify, and timestamp PDF files. You can also add and list signature fields, and check the validity of the digital signatures in a PDF document.
### Version 1.3.0
25 April 2024
#### Added
- Support for [mixed raster content](./optimize/optimization-profiles.mdx#mixed-raster-content-optimization-profile) (MRC) optimization. You can now use the mixed raster content optimization profile by using the `optimize-mrc` command with the Pdftools SDK Shell Tool.
- You can now enable or disable the [reduce color complexity](./optimize/optimization-profiles.mdx#mixed-raster-content-optimization-profile) by using the `-drc` option when performing PDF optimization.
### Version 1.2.0
12 April 2024
#### Added
- Support PDF to PDF/A file conversion. All supported PDF and PDF/A versions are listed in [Supported PDF versions](README.mdx#supported-pdf-versions).
- Support PDF file validation of conformance with PDF or PDF/A standards listed in [Supported PDF versions](README.mdx#supported-pdf-versions).
- Before version 1.2 the Pdftools SDK Shell Tool was only available as a framework-dependent .NET application. Now you can also download the Pdftools SDK Shell Tool as a self-contained application for Windows, Mac, and Linux.
### Version 1.1.0
19 January 2024
#### Added
- Support for merging and splitting PDF files to assemble new output documents.
- Support for rendering a PDF files to an image suitable for fax, archiving, or viewing.
### Version 1.0.0
22 September 2023
#### Added
- Support for converting images to PDF or PDF/A files
- Support compression and optimization of PDF files for web, archive, or print to minimize the file size.
---
## Sign and secure PDF documents
Digital signatures play a crucial role in verifying the authenticity and integrity of electronic documents or messages. Applying a digital signature to a PDF document allows the reader to verify that the document has not been tampered with or altered in any way, and that is was produced by the person who claims to have produced it.
PDF documents can be secured from unauthorized access by applying encryption, and by restricting access to specific users through passwords. Applying encryption to a PDF document ensures that the contents of the document can only be read by the audience for whom the document is intended.
With the Pdftools SDK, you can create, manage, and validate all types of digital signatures and encryption in PDF documents.
See the sections below for specific information about:
- [Signing PDF documents](sign/README.mdx)
- [PDF security](secure/README.mdx)
---
## Secure PDF documents
PDF documents can be protected from unauthorized access, restricting access to specific users with passwords and the use of encryption.
However, any PDF application that processes or displays a PDF document must read and decrypt the contents of the pages.
Technically, it cannot display an encrypted text or image without first decrypting it.
Therefore, a PDF application program has full access to any PDF document it can decrypt and display.
:::note Note about encryption and PDF/A
Encryption is not allowed by the PDF/A ISO standards.
For that reason, encryption options must not be used when processing PDF/A documents.
Otherwise, PDF/A conformance is removed from the output document.
For more information, see [PDF/A](/docs/knowledge/pdf-a/).
:::
The encryption process applies encryption to all streams (e.g. images) and strings, but not to other items in the PDF document.
This means the structure of the PDF document is accessible, but the content of its pages is encrypted.
The Pdftools SDK uses security handlers for **[encryption in PDF documents](pdf-encryption.mdx)**.
:::tip Get started
Learn **[how to encrypt a PDF document](encrypt-a-pdf.mdx)** with the Pdftools SDK.
:::
---
## Encrypt and decrypt a PDF document
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
The Pdftools SDK provides methods to open and save encrypted PDF documents.
The [PDF encryption process](pdf-encryption.mdx) applies encryption to all streams (e.g. images) and text, but not to other items in the PDF document.
This means the structure of the PDF document is accessible, but the content of its pages is encrypted.
## Opening an encrypted PDF document
:::tip Quick start with a code sample
Download the full encryption sample in:
- **[C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Decrypt/Download?technology=C)**
- **[C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Decrypt/Download?technology=CS)**
- **[Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Decrypt/Download?technology=Java)**
- **[Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Decrypt/Download?technology=Python)**
- **[Visual Basic](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Decrypt/Download?technology=VB)**
Download the full decryption sample in:
- **[C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Encrypt/Download?technology=C)**
- **[C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Encrypt/Download?technology=CS)**
- **[Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Encrypt/Download?technology=Java)**
- **[Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Encrypt/Download?technology=Python)**
- **[Visual Basic](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Encrypt/Download?technology=VB)**
Interested in Go, Rust or other programming language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.
:::
To open an encrypted PDF document, a password must be provided.
Up to two passwords can be specified for a document: an 'Owner' password and a 'User' password.
Permissions for a document depends on the type of password provided.
See [Permissions and passwords in PDF documents](pdf-encryption.mdx#permissions-and-passwords-in-pdf-documents).
:::note Before you begin
You need to **[initialize the library](/docs/licenses/products/pdf-tools-sdk-license/#activate-the-pdftools-sdk-license)**.
:::
In the Pdftools SDK, the password is provided as an optional parameter to the static `Document.Open` method.
```csharp
// Open an encrypted input document
// The password parameter is optional, and only required to open an encrypted PDF document
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr, password);
```
```java
// Open an encrypted input document
// The password parameter is optional, and only required to open an encrypted PDF document
FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
com.pdftools.pdf.Document inDoc = com.pdftools.pdf.Document.open(inStr, password)
```
If the PDF document is encrypted and the `password` parameter is not provided or is not valid, the `Document.Open` method fails with a `PasswordException`.
## Saving an encrypted PDF document
:::tip Quick start with a code sample
Download the full sample in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Encrypt/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Encrypt/Download?technology=Java), and [C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Encrypt/Download?technology=C).
Interested in other language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.
:::
With the Pdftools SDK, you can open and read encrypted PDF files using the standard security handler. You can encrypt output PDF documents, adding an owner password, a user password, or both.
This example shows how encryption is applied to the output document during the PDF optimization process. You can also apply encryption during other processes where `OutputOptions` are used, e.g. signing.
{/*sample source: PdfToolsSDK/Samples/Templates/encrypt.cs (with modifications)*/}
```csharp
// Create output stream
using var outStr = File.Create(outPath);
// Create output options and specify encryption parameters
// In this example, a 'User' is only granted permission to fill forms and print the document
var outOpt = new OutputOptions();
var outEnc = new Encryption(strUserPassword, strOwnerPassword, (Permission.FillForms | Permission.Print));
outOpt.Encryption = outEnc;
// Optimize the input PDF document and save it to a file, applying the specified output encryption
using var outDoc = optimizer.OptimizeDocument(inDoc, outStr, profile, outOpt);
```
{/*sample source: PdfToolsSDK/Samples/Templates/encrypt.java (with modifications)*/}
```java
// Create output stream
FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW);
// Create output options and specify encryption parameters
// In this example, a 'User' is only granted permission to fill forms and print the document
OutputOptions outOpt = new OutputOptions();
// Set a user password that is required to open the document.
// Note that this removes PDF/A conformance of input files (see warning category WarningCategory.PDF_A_REMOVED)
outOpt.setEncryption(new Encryption(strUserPassword, strOwnerPassword, EnumSet.of(Permission.FILL_FORMS, Permission.PRINT)));
// Optimize the input PDF document and save it to a file, applying the specified output encryption
Document outDoc = new Optimizer().optimizeDocument(inDoc, outStr, profile, outOpt));
```
## Removing encryption from an encrypted PDF document
Removing encryption from an encrypted document is as simple as the process for encrypting the document.
After you have opened the encrypted document as shown above, the document can be processed in the same way as for encryption, but setting the `Encryption` to `null`.
{/*sample source: PdfToolsSDK/Samples/Templates/decrypt.cs (extract only)*/}
```csharp
// Create output options and remove encryption by setting it to null
var outOpt = new OutputOptions();
outOpt.Encryption = null;
```
{/*sample source: PdfToolsSDK/Samples/Templates/decrypt.java (extract only)*/}
```java
// Create output options and remove encryption by setting it to null
OutputOptions outOpt = new OutputOptions();
outOpt.setEncryption(null);
```
---
## Encryption in PDF documents
When encryption is used in PDF, a security handler must be selected. The Pdftools SDK always uses the standard security handler that, according to the PDF Specification, must be supported by any software that can process encrypted PDF documents.
:::tip
For more detailed information about PDF encryption in general, consult **[PDF Reference, chapter 3.5](https://opensource.adobe.com/dc-acrobat-sdk-docs/pdfstandards/pdfreference1.7old.pdf#3.5-encryption)**.
:::
## Permissions and passwords in PDF documents
The standard security handler allows access permissions for the document. Up to two passwords can be specified for a document:
- [Owner password](#owner-password)
- [User password](#user-password)
### Owner password
An owner password is also referred to as the author's password. This password grants full access to the document.
It allows the document be opened and read, and also lets the document's security settings (access permission and passwords) to be changed.
### User password
A user password protects the document against unauthorized opening and reading.
If a PDF document is protected by a user password, either the user or owner password must be provided to open and read the document.
If a document has a user password, it must have an owner password as well.
If no owner password is defined, the owner password is the same as the user password.
The following table shows the four possible combinations of passwords and how an application processing such a
PDF document behaves.
| User password | Owner password | Behavior |
| ------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| None | None | Everyone can read. Everyone can change security settings. (No encryption) |
| None | Set | Everyone can read. The user password is an empty string. Owner password required to change security settings. |
| Set | None | User password required to read. The owner password is equal to the user password. User password required to change security settings. |
| Set | Set | User or owner password required to read. Owner password required to change security settings. |
### Permission flags
The operations granted in a PDF document are controlled by permission flags. To set permission flags, the PDF document must be encrypted and have an owner password. The owner password is required to initially set or later change the permission flags.
These access permission flags determine operations such as:
- Modify the content of the document
- Copy or extract text and graphics from the document
- Add or modify text annotations and interactive form fields
- Print the document (low or high quality)
- Fill in forms and digitally sign the document
- Assemble the document (insert, rotate, delete pages, etc.)
## Reading a PDF document
A PDF document that is not encrypted or protected with an owner password only can be read and decrypted by the Pdftools SDK `Open` function without providing a password.
A PDF document that is protected by a user password can only be opened if either the user or the owner password is provided as parameter in the `Open` function.
Technically, it does not matter later on which of the two passwords was provided, because both grant full access to the document.
However, it is up to the application programmer to distinguish between input documents that are password protected or not.
## Encrypting a PDF document
If either of the passwords or permission flags is set, the document is encrypted. If only a user password is set, but no owner password and no permission flags, the owner password is equal to the user password and all permissions are granted.
To encrypt a document and protect it against any manipulations other than printing, the document must have an owner password and the print permission flag set.
:::note
To learn how to encrypt and decrypt a document with the Pdftools SDK, see [Encrypt a PDF](encrypt-a-pdf.mdx).
:::
## Security and PDF encryption
PDF application programs such as all products of the Pdftools family or Adobe Acrobat can open and decrypt PDF documents that have an owner password but no user password, without knowing that password. Otherwise, it couldn't display the document. The application at that point has full access to the document.
However, this does not imply the user of this application is given the same access rights. The user should only be given the access permissions defined by the permission flags and the password provided.
Any PDF application that behaves different from that can allow for changing the security settings or completely removing encryption from the document as long as the original document does not have a user password.
The user password protects the document, so that it only can be opened if the user or owner password is known. No PDF application program can open a user-password protected PDF document without providing the password.
However, the security of such a document strongly depends on the password itself. Like in most password-related situations, insecure passwords can easily be found programmatically. For example, a brute force attempt testing all passwords that either exist as word in a dictionary or have less than six characters only takes minutes.
---
## Sign PDF documents
With the Pdftools SDK, you can create, manage, and validate different types of [digital signatures](#digital-signature-types) in a PDF document.
You can choose from a variety of local and online [cryptographic providers](#supported-cryptographic-providers) to support your legal and regulatory requirements.
## Digital signature types
A digital signature is a technique used to verify the authenticity and integrity of an electronic document or message.
It is created by applying a cryptographic algorithm to the document or message, using a private key.
The resulting digital signature can then be [verified](#validating-signatures) using the corresponding public key, which is made available to anyone who wants to verify the signature.
Digital signatures are used to ensure that a document or message has not been tampered with or altered in any way, and that it was sent by the person who claims to have sent it.
The Pdftools SDK supports three types of digital signature:
- **[Document approval signatures](#document-approval-signatures)**
- **[Document certification signatures](#document-certification-signatures)**
- **[Time-stamp signatures](#time-stamp-signatures)**
:::tip
For theoretical information about digital signatures, review [Digital signature basics](/docs/knowledge/digital-signature-basics/).
:::
### Document approval signatures
Document approval signatures add a digital signature to a document as part of a workflow, such as approving and signing contracts.
This type of digital signature records the identity of the signer, and confirms that the content of the document has not changed after the signature was applied.
There can be multiple document approval signatures associated with a document.
For example, if multiple parties sign a contract, each document approval signature has a unique digital signature.
The signatures are applied successively to create a signature chain.
:::tip Get started
Learn how to **[sign a PDF document](sign-document.mdx)** with a document approval signature.
:::
### Document certification signatures
Document certification signatures are also known as Modification Detection and Prevention (MDP) signatures.
This type of signatures records the identity of the document author. It allows users to make specific changes to the document, while retaining the validity of the signature.
For example, the author may allow a document's form fields to be filled by the user, while retaining the validity of the signature.
If changes occur to the document that have not been permitted by the author, the signature is invalidated.
There can be at most one document certification signature in a document, and it must be added before any other signatures are added to the document.
A typical workflow involving a document certification signature would be:
1. A document certification signature is applied to a template document, allowing form filling.
2. A user fills the form fields with their personal information.
3. A [document approval signature](#document-approval-signatures) is applied to the document, preventing any further changes from being made.
The following settings can be used for document certification signatures:
- **No changes**: No changes to the document are permitted; any change to the document invalidates the signature.
- **Form filling**: The user may fill forms, instantiate page templates, and sign; any other change invalidates the signature.
- **Annotate**: The user may make the same changes as for form filling, as well as create, delete, and modify annotations; any other change invalidates the signature.
:::tip Get started
Learn how to **[certify a PDF document](sign-certify.mdx)** with a document certification signature.
:::
### Time-stamp signatures
Time-stamp signatures provide evidence that a document existed at a specific time, and that the content of the document has not changed since that time.
Often, time-stamp signatures are used to "re-sign" a previously signed document to confirm that it remains unchanged.
The time-stamp is provided by an independent, [trusted time-stamp authority](timestamp-authority.mdx).
:::tip Get started
Learn how to **[apply a digital time-stamp to a PDF document](sign-timestamp.mdx)** with a time-stamp signature.
:::
## Supported cryptographic providers
The cryptographic provider manages certificates and the associated private keys, and implements cryptographic algorithms.
The Pdftools SDK supports a range of [cryptographic providers](cryptographic-providers.mdx).
## Embedding long-term validation information
To ensure a signature can be validated over time, [long-term validation information](long-term-validation.mdx) should be embedded in the document during the signing process. If you embed LTV information in a document, the signature in the document remains valid even after the certificate expires or if the certificate is later revoked.
:::note
Long-term validation (LTV) is not always possible. It must be supported by the certificate authority and the cryptographic provider.
:::
## Signing PDF/A documents
Many types of documents that require digital signatures also require archiving. For example, by the recipient of a signed contract.
For archiving, PDF/A conformance is typically required to ensure that the file is not corrupt and that its visual appearance is well defined and reproducible.
However, during the [conversion process from PDF to PDF/A](../../archive/archive-pdf-pdfa.mdx), any signatures are removed from the file before it is converted to PDF/A for archival.
Therefore, files that require archiving should be [archived to PDF/A format](../../archive/archive-pdf-pdfa.mdx) before any digital signatures are applied.
## Validating signatures
The Pdftools SDK lets you validate document approval and document certification signatures and timestamps according to a specific criteria (constraints).
Signatures can be validated using sources such as certificates, Online Certificate Status Protocol (OCSP) results, and Certificate Revocation List (CRL) results. These sources can be embedded in the PDF file, stored on the local machine, or downloaded from the issuer.
The validation process can return a list of all signatures and their corresponding details and even trigger specific business logic using events.
:::tip Get started
Learn how to **[validate signatures](sign-validate.mdx)** in a document.
:::
## Creating a signature visual appearance
The Pdftools SDK allows for adding a [visual appearance](signature-appearance.mdx) for a signature.
This applies for [document approval signatures](#document-approval-signatures), [document certification signatures](#document-certification-signatures), [time-stamp signatures](#time-stamp-signatures) and signing existing unsigned signatures.
---
## Set up digital signing for Pdftools SDK
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
Depending on the type of digital signature you want to add to documents using the Pdftools SDK, you may need to:
- Configure the connection to a remote service using [HTTPS connection](#configuring-https-connections)
- Store certificates in a [local directory](#storing-local-certificates) recognized by the SDK
- Set up the SDK to route requests via a [proxy server](#using-a-proxy-server)
## Configuring HTTPS connections
When the Pdftools SDK connects to a remote service using HTTPS (SSL/TLS) communication, the server certificate's trustworthiness is verified by the `HttpClientHandler` class.
If the verification process fails, the connection to the server is aborted.
The verification process requires a trust store; otherwise, verification always fails.
The system's default trust store is used.
Additional trusted certificates may be added using the `AddTrustedCertificate` method of the `HttpClientHandler` class.
When an SSL/TLS connection requires a client certificate (for example, when connecting to an online signing service), the `SetClientCertificate` and `SetClientCertificateAndKey` methods of the `HttpClientHandler` class are used to set the client certificate and its private key.
The default trust store is configured in the following locations:
The Windows certificate store for _Trusted Root Certification Authorities_ is used.
You can install the root certificate of a private CA manually on a computer by using the `CertMgr` tool.
The certificate store is only available if the user profile has been loaded.
The certificates available in `CAfile` and `CApath` are trusted:
### CAfile
The file can contain a concatenated sequence of CA certificates in PEM format.
The SDK searches for the file at the following locations:
- The file of your local OpenSSL installation (if `libssl.so` is found), or
- the environment variable `SSL_CERT_FILE`, or
- the default location `/etc/ssl/cert.pem`
### CApath
A directory containing CA certificates in PEM format.
The files are looked up by the CA subject name hash value. For example, `9d66eef0.0`.
The SDK searches for the directory at the following locations:
- The directory of your local OpenSSL installation (if `libssl.so` is found), or
- the environment variable `SSL_CERT_DIR`, or
- the default location `/etc/ssl/certs/`
The trusted certificates from the macOS keychain are used.
You can install the root certificate of a private CA manually by dragging the certificate file to the `Keychain Access` app.
:::note
If it is not possible to verify the server certificate, you can disable verification by setting the `SslVerifyServerCertificate` property of the `HttpClientHandler` to `false`.
However, this approach is strongly discouraged in any production environment.
:::
## Storing local certificates
When [signing PDF documents](sign-document.mdx), additional certificates may be required.
For example, you may need additional certificates when the `OutputOptions` class is configured to add all certificates of the signing certificate's trust chain to the output document security store (DSS) to enable [long-term signature validation (LTV)](long-term-validation.mdx).
If the certificate provider allows certificates to be downloaded, the Pdftools SDK downloads the required certificates and stores them in a local `Certificates` directory.
You may also manually add certificates to the `Certificates` directory.
The Pdftools SDK stores and searches for local certificates, in either PEM (.pem, ASCII text) or DER (.cer, binary) format, in the following locations:
```
%LOCALAPPDATA%\PDF Tools AG\Certificates
%ProgramData%\PDF Tools AG\Certificates
```
```
~/.pdf-tools/Certificates or $TMP/pdf-tools/Certificates
/usr/share/pdf-tools/Certificates
```
```
~/.pdf-tools/Certificates or $TMP/pdf-tools/Certificates
```
## Using a proxy server
Some of the features of the Pdftools SDK require access to a remote service.
These features include:
- Connecting to a [time-stamp authority (TSA)](timestamp-authority.mdx) to retrieve a time-stamp
- Connecting to an [online signing service](cryptographic-providers.mdx#online-signing-services) to access document signing functions
- Connecting to a certificate authority to retrieve certificates and revocation information
If your software runs in a secured environment, it may be necessary or preferable to configure a proxy server to route requests from the Pdftools SDK to these remote services.
To configure a proxy, assign the `PdfTools.Sdk` class a `Proxy` server URI that the SDK will use for all HTTP and HTTPS communications with remote services.
### Proxy server URI
The default value for the `Proxy` server URI property is `null`, meaning that no proxy is used.
Otherwise, the property’s value must be a URI with the following elements:
http[s]://[USER[:PASSWORD]@]HOST[:PORT]
Where:
- `http`/`https`: Protocol for connection to proxy.
- `USER:PASSWORD` (optional): Credentials for connection to proxy (basic authorization).
- `HOST`: Hostname of proxy.
- `PORT`: Port for connection to proxy
Example: `http://user:password@myproxy:8080`
### SSL/TLS connections to online signing services
For SSL/TLS connections (for example, to the [GlobalSign](provider-globalsign.mdx) or [Swisscom](provider-swisscom.mdx) signature services), the proxy must allow `HTTP CONNECT` requests to the remote server.
### Connections to time-stamp authorities
If you want to sign documents using time-stamp certificates, the following MIME types must be supported:
- `application/timestamp-query`
- `application/timestamp-reply`
### Embedded long-term validation information
If you plan to embed [long-term validation](long-term-validation.mdx) information in the digital signatures, then the following MIME types must be supported:
- `application/ocsp-request`
- `application/ocsp-response`
---
## Cryptographic providers(Sign)
For digital signatures to be applied to a document, a cryptographic provider must be configured.
The cryptographic provider manages certificates and the associated private keys, and implements cryptographic algorithms.
The cryptographic provider used impacts the legal effect of your digital signatures, and often depends on your local legal and regulatory requirements.
If you are unsure of these requirements, contact your local Certificate Authority (CA) for guidance.
The Pdftools SDK supports a range of cryptographic providers:
- [Built-in cryptographic provider](#built-in-cryptographic-provider)
- [PKCS#11 provider](#pkcs11-provider)
- [Online signing services](#online-signing-services), e.g. GlobalSign and Swisscom
## Built-in cryptographic provider
The built-in cryptographic provider requires no cryptographic hardware or external service, except for an optional connection to an external time-stamp service.
Signing certificates with private keys can be loaded directly from a PFX (PKCS#12) soft certificate stored as a local file, using the Pdftools SDK.
Additional certificates can be stored in a local [Certificates directory](configure-digital-signing.mdx#storing-local-certificates).
These additional certificates are required when adding validation information to signatures that do not have the full trust chain embedded.
The certificates directory may contain certificates in either PEM (.pem, ASCII text) or DER (.cer, binary) format.
:::tip Get started
Learn [how to sign a PDF document using the built-in cryptographic provider](provider-builtin.mdx).
:::
## PKCS#11 provider
The PKCS#11 provider creates a session to a cryptographic device (HSM, USB token, etc.) to perform cryptographic operations.
It requires a driver module (middleware).
More information on the driver required can be found in the documentation for your cryptographic device.
The [PKCS#11 Tech Note](https://www.pdf-tools.com/public/downloads/manuals/TechNotePKCS11.pdf) provides detailed information about configuring a PKCS#11 device to work with the Pdftools SDK.
:::tip Get started
Learn [how to sign a PDF document using a PKCS#11 device](provider-pkcs11.mdx).
:::
## Online Signing Services
Online signing services are cloud-based cryptographic providers that enable their customers to sign documents and provide them with time-stamps.
### GlobalSign Digital Signing Service
This provider implements the methods of the [GlobalSign Digital Signing Service](https://www.globalsign.com/en/digital-signatures). A GlobalSign account is required.
:::tip Get started
Learn [how to sign a PDF document using the GlobalSign Digital Signing Service](provider-globalsign.mdx).
:::
### Swisscom Signing Service
This provider implements the methods of the [Swisscom Signing Service](https://trustservices.swisscom.com/en/signing-service/). A Swisscom account is required.
:::tip Get started
Learn [how to sign a PDF document using the Swisscom Signing Service](provider-swisscom.mdx).
:::
---
## Embed long-term validation (LTV) information
The Pdftools SDK can be configured to embed long-term validation (LTV) information into a document during the [document signing process](sign-document.mdx).
When the Pdftools SDK is configured to embed LTV information, it attempts to embed revocation information such as **online certificate status response** ([OCSP - RFC2560](https://datatracker.ietf.org/doc/html/rfc2560)) and **certificate revocation lists** ([CRL - RFC3280](https://datatracker.ietf.org/doc/html/rfc3280)).
Revocation information is provided by a validation service at the time of signing and acts as proof that the certificate was valid at the time of signing.
Embedding revocation information is optional, but recommended when applying advanced (AES) or qualified electronic signatures (QES).
Revocation information is embedded for the signing certificate and all certificates of its trust chain.
Therefore, both OCSP responses and CRLs may be present in the same message.
However, embedding revocation information increases the file size (usually around 20 kB), and requires an external request to a validation service, which may delay the signing process.
:::note LTV in time-stamp signatures
Long-term validation (LTV) information cannot be embedded directly for [time-stamp signatures](sign-timestamp.mdx).
Instead, after the time-stamp signature has been applied, the `Process` method of the `Signer` class must be invoked again to embed LTV information for each of the certificates in the document.
:::
## HTTPS connections
When retrieving certificate revocation information from a remote server using HTTPS (SSL/TLS) communication, the server certificate's trustworthiness is verified using the system's default trust store (CA certificate store).
You need to [set up the HTTPS connection](configure-digital-signing.mdx#configuring-https-connections) to communicate with the Pdftools SDK.
## Proxy server
In a secured environment, the firewall must be configured to allow connection to the remote server. If you [use a proxy server](configure-digital-signing.mdx#using-a-proxy-server), the following MIME types must be supported:
- `application/ocsp-request`
- `application/ocsp-response`
---
## Built-in cryptographic provider
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
The `BuiltIn` cryptographic provider enables access to the cryptographic functions of the local operating system. For example, to [sign a document](sign-document.mdx).
No cryptographic hardware or external service is required, except for the optional `TimestampUrl` used when appling a [time-stamp](sign-timestamp.mdx).
You can load signing certificates with private keys directly from a PFX (PKCS#12) file using the `CreateSignatureFromCertificate` method.
Additional certificates (for example, issuer certificates) are stored in the [Certificates directory](configure-digital-signing.mdx#storing-local-certificates).
These certificates are required when adding validation information to signatures that do not have the full trust chain embedded.
The [Certificates directory](configure-digital-signing.mdx#storing-local-certificates) may contain certificates in either PEM (.pem, ASCII text) or DER (.cer, binary) form.
In this example, a `BuiltIn` cryptographic provider is used to apply a document approval signature to a PDF document.
The PFX certificate is read from a local file.
Information required for long-term signature validation (LTV) is embedded in the output PDF.
**Steps to sign a document**:
1. [Initialize the cryptographic provider](#initializing-the-cryptographic-provider).
2. [Read the PFX or P12 certificate](#reading-the-pfx-or-p12-certificate).
3. [(Optional) Add long-term validation information](#adding-long-term-validation-information)
4. [Open and sign the document](#opening-and-signing-the-document).
---
:::note Before you begin
You need to **[initialize the library](/docs/licenses/products/pdf-tools-sdk-license/#activate-the-pdftools-sdk-license)**.
:::
## Initializing the cryptographic provider
When using the `BuiltIn` cryptographic provider, you start the digital signing process by instantiating the `Provider` object.
The `Provider` object exposes the methods of the local operating system's cryptographic provider.
The cryptographic provider manages certificates and private keys, and implements cryptographic algorithms.
```csharp
// Create a session to the built-in cryptographic provider
using var session = new BuiltIn.Provider();
```
```java
// Create a session to the built-in cryptographic provider
Provider session = new Provider();
```
## Reading the PFX or P12 certificate
PFX certificate files can be loaded directly into the `BuiltIn` cryptographic provider from the file system.
The certificate file is opened as a stream and loaded into the provider to prepare it to apply a digital signature.
```csharp
// Create signature configuration from PFX (or P12) file
using var pfxStr = File.OpenRead(certificateFile);
var signature = session.CreateSignatureFromCertificate(pfxStr, password);
```
```java
// Create signature configuration from PFX (or P12) file
FileStream pfxStr = new FileStream(certificateFile, FileStream.Mode.READ_ONLY));
SignatureConfiguration signature = session.createSignatureFromCertificate(pfxStr, password);
```
:::tip
If you are using a Java `KeyStore` that has already been loaded, for example `ks`, you can use a `MemoryStream` to create the `SignatureConfiguration`.
```java
// Create an OutputStream to write the KeyStore to (into memory)
ByteArrayOutputStream os = new ByteArrayOutputStream();
// Write the KeyStore to the OutputStream
ks.store(os, password.toCharArray());
// Put the OutputStream bytes into a MemoryStream
Stream certStr = new MemoryStream(os.toByteArray());
// Create signature configuration from that MemoryStream
SignatureConfiguration signature = session.createSignatureFromCertificate(certStr, password);
```
The `KeyStore` must be of type `PKCS12`.
For more information on the `KeyStore`, please refer to the [Java API Reference](https://docs.oracle.com/javase/8/docs/api/java/security/KeyStore.html).
:::
## Adding long-term validation information
As an optional step, [long-term validation](long-term-validation.mdx) information can be added to the output document.
It embeds revocation information such as online certificate status response and certificate revocation lists.
Revocation information is provided by a validation service at the time of signing and acts as proof that the certificate was valid at the time of signing.
```csharp
// Embed validation information to enable the long-term validation (LTV) of the signature
signature.ValidationInformation = PdfTools.Crypto.ValidationInformation.EmbedInDocument;
```
```java
// Embed validation information to enable the long term validation (LTV) of the signature (default)
signature.setValidationInformation(com.pdftools.crypto.ValidationInformation.EMBED_IN_DOCUMENT);
```
## Opening and signing the document
After instantiating the `Provider` and preparing the signature configuration, you are ready to apply the digital signature to a document.
The input and output PDF documents are created as streams (in this example, as file streams). The `Signer` object is used to apply the digital document signature.
Non-critical processing errors raise a `Warning` event.
It is recommended to listen for these events, and review the `WarningCategory` to determine if further action is needed.
```csharp
// Open the input document
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);
// Create a stream for the output file
using var outStr = File.Create(outPath);
// Create the Signer object
Signer signer = new Signer();
// (optionally) Create an event listener to listen for warning events that are raised and write them to console
signer.Warning += (s, e) => Console.WriteLine("Warning - {0}: {1}: {2}", e.Category, e.Context, e.Message);
// Sign the output document
using var outDoc = signer.Sign(inDoc, signature, outStr);
```
```java
// Open input document
FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
Document inDoc = Document.open(inStr);
// Create a stream for the output file
FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW);
// Create the Signer object
Signer signer = new Signer();
// (optionally) Create an event listener to listen for warning events that are raised and write them to console
signer.addWarningListener((e) -> { System.out.format("Warning - %s: %s: %s", e.getCategory(), e.getContext(), e.getMessage()); });
// Sign the input document
Document outDoc = signer.sign(inDoc, signature, outStr);
```
## Full example
{/*sample source: PdfToolsSDK/Samples/Templates/builtinsign.cs*/}
```csharp
// Create a session to the built-in cryptographic provider
using var session = new BuiltIn.Provider();
// Create signature configuration from PFX (or P12) file
using var pfxStr = File.OpenRead(certificateFile);
var signature = session.CreateSignatureFromCertificate(pfxStr, password);
// Embed validation information to enable the long-term validation (LTV) of the signature (default)
signature.ValidationInformation = PdfTools.Crypto.ValidationInformation.EmbedInDocument;
// Open input document
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);
// Create stream for output file
using var outStr = File.Create(outPath);
// Create the Signer object
Signer signer = new Signer();
// Create an event listener to listen for warning events that are raised and write them to console
signer.Warning += (s, e) => Console.WriteLine("Warning - {0}: {1}: {2}", e.Category, e.Context, e.Message);
// Sign the output document
using var outDoc = signer.Sign(inDoc, signature, outStr);
```
{/*sample source: PdfToolsSDK/Samples/Templates/builtinsign.java*/}
```java
try (
// Create a session to the built-in cryptographic provider
Provider session = new Provider();
// Open certificate file
FileStream pfxStr = new FileStream(certificateFile, FileStream.Mode.READ_ONLY))
{
// Create signature configuration from PFX (or P12) file
SignatureConfiguration signature = session.createSignatureFromCertificate(pfxStr, password);
// Embed validation information to enable the long term validation (LTV) of the signature (default)
signature.setValidationInformation(com.pdftools.crypto.ValidationInformation.EMBED_IN_DOCUMENT);
// Create the Signer object
Signer signer = new Signer();
// (optionally) Create an event listener to listen for warning events that are raised and write them to console
signer.addWarningListener((e) -> { System.out.format("Warning - %s: %s: %s", e.getCategory(), e.getContext(), e.getMessage()); });
try (
// Open input document
FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
Document inDoc = Document.open(inStr);
// Create a stream for the output file
FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW);
// Sign the input document
Document outDoc = signer.sign(inDoc, signature, outStr))
{
}
}
```
:::important Signing PDF/A documents
During the [conversion process from PDF to PDF/A](../../archive/archive-pdf-pdfa.mdx), any signatures are removed from the file before it is converted to PDF/A for archiving.
Therefore, files that require archiving should be [archived to PDF/A format](../../archive/archive-pdf-pdfa.mdx) before any digital signatures are applied.
:::
---
## GlobalSign cryptographic provider
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
The `GlobalSignDss` cryptographic provider enables access to the [GlobalSign Digital Signing Service](https://www.globalsign.com/en/digital-signatures) (GlobalSign DSS).
The service can then be used to perform cryptographic functions such as [sign a document](sign-document.mdx).
This provider requires a GlobalSign DSS account.
Accounts with static and dynamic identities are supported.
:::tip Quick start with a code sample
Download the full sample now in **[C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/GlobalSignDssSign/Download?technology=CS)**, **[Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/GlobalSignDssSign/Download?technology=Java)**, **[Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/GlobalSignDssSign/Download?technology=Python)**, and **[Visual Basic](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/GlobalSignDssSign/Download?technology=VB)**.
Interested in C, Go, Rust or other programming language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.
:::
The GlobalSign DSS provides signing certificates and basic cryptographic (PKCS#1) signatures.
Additional certificates such as issuer certificates are stored in the [Certificates directory](configure-digital-signing.mdx#storing-local-certificates).
These certificates are required when adding validation information to signatures that do not have the full trust chain embedded.
The [Certificates directory](configure-digital-signing.mdx#storing-local-certificates) may contain certificates in either PEM (.pem, ASCII text) or DER (.cer, binary) form.
In this example, the `GlobalSignDss` cryptographic provider is used to apply a document approval signature to a PDF document.
The signing certificate is loaded from the GlobalSign DSS.
An account that supports dynamic identities is used.
The signing certificate is identified by passing the common name of the certificate.
Information required for long-term signature validation (LTV) is embedded in the output PDF.
**Steps to sign a document**:
1. [Configure the HTTP client handler](#configuring-the-http-client-handler).
2. [Connect to GlobalSign DSS](#connecting-to-globalsign-dss).
3. [Create the document signature](#creating-the-document-signature).
4. [(Optional) Add long-term validation information](#adding-long-term-validation-information).
5. [Open and sign the document](#opening-and-signing-the-document).
---
:::note Before you begin
You need to **[initialize the library](/docs/licenses/products/pdf-tools-sdk-license/#activate-the-pdftools-sdk-license)**.
:::
## Configuring the HTTP client handler
When using the `GlobalSignDss` cryptographic provider, you need to configure the `HttpClientHandler` with the SSL client certificate, private key, and password from your GlobalSign DSS account.
```csharp
// Configure the SSL client certificate to connect to the GlobalSign DSS service
var httpClientHandler = new HttpClientHandler();
using (var sslClientCert = File.OpenRead(@"C:\path\to\clientcert.cer"))
using (var sslClientKey = File.OpenRead(@"C:\path\to\privateKey.key"))
httpClientHandler.SetClientCertificateAndKey(sslClientCert, sslClientKey, password);
```
```java
// Configure the SSL client certificate to connect to the service
HttpClientHandler httpClientHandler = new HttpClientHandler();
try (
FileStream sslClientCert = new FileStream("C:/path/to/clientcert.cer", FileStream.Mode.READ_ONLY);
FileStream sslClientKey = new FileStream("C:/path/to/privateKey.key", FileStream.Mode.READ_ONLY))
{
httpClientHandler.setClientCertificateAndKey(sslClientCert, sslClientKey, password);
}
```
## Connecting to GlobalSign DSS
The next step is to open a `Session` to the GlobalSign DSS by logging in with the API key and secret from your GlobalSign DSS account.
The `Session` object provides access to the certificates and private keys stored by GlobalSign.
In this example, the default URI for the GlobalSign DSS is used.
### Advice on using the service
Whenever you create a new GlobalSign `Session`, a login is performed.
In this session, signatures can be created using different identities, i.e. signing certificates, which are created as they are needed.
Both signing sessions and signing certificates expire after 10 minutes.
There are rate limits for both creating new identities and for signing operations.
If multiple documents must be signed at once, you should re-use the same session (and hence its signing certificates) for signing.
Due to the short-lived nature of the signing certificates, it is important to embed revocation information immediately.
For example, by using `AddValidationInformation` or `EmbedRevocationInfo`.
Furthermore, it is highly recommended to embed a timestamp to prove that the signature was created during the certificate’s validity period.
```csharp
// Connect to the GlobalSign Digital Signing Service
using var session = new GlobalSignDss.Session(new Uri("https://emea.api.dss.globalsign.com:8443"), apiKey, apiSecret, httpClientHandler);
```
```java
Session session = new Session(new URI("https://emea.api.dss.globalsign.com:8443"), apiKey, apiSecret, httpClientHandler);
```
## Creating the document signature
In this step, the `Session` object is used to create a signature configuration for a GlobalSign DSS account that supports dynamic identities.
The signing certificate is identified by passing the common name of the certificate.
The signature configuration may be used to sign one or more documents.
:::tip
If multiple documents must be signed at once, you should re-use the same session (and hence its signing certificates) for signing.
:::
```csharp
// Create a signing certificate for an account with a dynamic identity
// This can be re-used to sign multiple documents
var identity = JsonSerializer.Serialize(new { subject_dn = new { common_name = commonName } });
var signature = session.CreateSignatureForDynamicIdentity(identity);
```
```java
// Create a signing certificate for an account with a dynamic identity
// This can be re-used to sign multiple documents
SignatureConfiguration signature = session.createSignatureForDynamicIdentity(String.format("{ \"subject_dn\" : { \"common_name\" : \"%s\" } }", commonName));
```
## Adding long-term validation information
As an optional step, [long-term validation](long-term-validation.mdx) information can be added to the output document.
It embeds revocation information such as online certificate status response and certificate revocation lists.
Revocation information is provided by a validation service at the time of signing and acts as proof that the certificate was valid at the time of signing.
```csharp
// Embed validation information to enable the long-term validation (LTV) of the signature
signature.ValidationInformation = PdfTools.Crypto.ValidationInformation.EmbedInDocument;
```
```java
// Embed validation information to enable the long-term validation (LTV) of the signature (default)
signature.setValidationInformation(ValidationInformation.EMBED_IN_DOCUMENT);
```
## Opening and signing the document
After opening the `Session` and creating the signature configuration, you are ready to apply the digital signature to a document.
The input and output PDF documents are created as streams (in this example, as file streams). The `Signer` object is used to apply the digital document signature.
Non-critical processing errors raise a `Warning` event. It is recommended to listen for these events, and review the `WarningCategory` to determine if further action is needed.
```csharp
// Open the input document
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);
// Create a stream for the output file
using var outStr = File.Create(outPath);
// Create the Signer object
Signer signer = new Signer();
// Create an event listener to listen for warning events that are raised and write them to console
signer.Warning += (s, e) => Console.WriteLine("Warning - {0}: {1}: {2}", e.Category, e.Context, e.Message);
// Sign the output document
using var outDoc = signer.Sign(inDoc, signature, outStr);
```
```java
// Open input document
FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
Document inDoc = Document.open(inStr);
// Create output stream
FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW);
// Create the Signer object
Signer signer = new Signer();
// (optional) Create an event listener to listen for warning events that are raised and write them to console
signer.addWarningListener((e) -> { System.out.format("Warning - %s: %s: %s", e.getCategory(), e.getContext(), e.getMessage()); });
// Sign the input document
Document outDoc = signer.sign(inDoc, signature, outStr);
```
## Full example
{/*sample source: PdfToolsSDK/Samples/Templates/globalsigndsssign.cs*/}
```csharp
// Configure the SSL client certificate to connect to the GlobalSign DSS service
var httpClientHandler = new HttpClientHandler();
using (var sslClientCert = File.OpenRead(@"C:\path\to\clientcert.cer"))
using (var sslClientKey = File.OpenRead(@"C:\path\to\privateKey.key"))
httpClientHandler.SetClientCertificateAndKey(sslClientCert, sslClientKey, password);
// Connect to the GlobalSign Digital Signing Service
using var session = new GlobalSignDss.Session(new Uri("https://emea.api.dss.globalsign.com:8443"), apiKey, apiSecret, httpClientHandler);
// Create a signing certificate for an account with a dynamic identity
var identity = JsonSerializer.Serialize(new { subject_dn = new { common_name = commonName } });
var signature = session.CreateSignatureForDynamicIdentity(identity);
// Embed validation information to enable the long-term validation (LTV) of the signature
signature.ValidationInformation = PdfTools.Crypto.ValidationInformation.EmbedInDocument;
// Open the input document
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);
// Create a stream for the output file
using var outStr = File.Create(outPath);
// Create the Signer object
Signer signer = new Signer();
// Create an event listener to listen for warning events that are raised and write them to console
signer.Warning += (s, e) => Console.WriteLine("Warning - {0}: {1}: {2}", e.Category, e.Context, e.Message);
// Sign the output document
using var outDoc = signer.Sign(inDoc, signature, outStr);
```
{/*sample source: PdfToolsSDK/Samples/Templates/globalsigndsssign.java*/}
```java
// Configure the SSL client certificate to connect to the service
HttpClientHandler httpClientHandler = new HttpClientHandler();
try (
FileStream sslClientCert = new FileStream("C:/path/to/clientcert.cer", FileStream.Mode.READ_ONLY);
FileStream sslClientKey = new FileStream("C:/path/to/privateKey.key", FileStream.Mode.READ_ONLY))
{
httpClientHandler.setClientCertificateAndKey(sslClientCert, sslClientKey, "***insert password***");
}
// Connect to the GlobalSign Digital Signing Service
try (Session session = new Session(new URI("https://emea.api.dss.globalsign.com:8443"), apiKey, apiSecret, httpClientHandler))
{
// Create a signing certificate for an account with a dynamic identity
// This can be re-used to sign multiple documents
SignatureConfiguration signature = session.createSignatureForDynamicIdentity(String.format("{ \"subject_dn\" : { \"common_name\" : \"%s\" } }", commonName));
// Embed validation information to enable the long-term validation (LTV) of the signature (default)
signature.setValidationInformation(ValidationInformation.EMBED_IN_DOCUMENT);
// Create the Signer object
Signer signer = new Signer();
// (optional) Create an event listener to listen for warning events that are raised and write them to console
signer.addWarningListener((e) -> { System.out.format("Warning - %s: %s: %s", e.getCategory(), e.getContext(), e.getMessage()); });
try (
// Open input document
FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
Document inDoc = Document.open(inStr);
// Create output stream
FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW);
// Sign the input document
Document outDoc = signer.sign(inDoc, signature, outStr))
{
}
}
```
---
## PKCS#11 cryptographic provider
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
The `Pkcs11` cryptographic provider enables access to a cryptographic device using a PKCS#11 driver module. The cryptographic device can then be used to perform cryptographic functions such as [sign a document](sign-document.mdx).
This provider requires a PKCS#11 driver module (middleware) to establish a session to a cryptographic device of a particular type. For example, a HSM, Cloud KMS, or USB token.
:::tip Quick start with a code sample
Download the full sample now in **[C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pkcs11Sign/Download?technology=CS)**, **[Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pkcs11Sign/Download?technology=Java)**, **[Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pkcs11Sign/Download?technology=Python)**, and **[Visual Basic](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pkcs11Sign/Download?technology=VB)**.
Interested in C, Go, Rust or other programming language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.
:::
More information on the driver required can be found in the documentation for your cryptographic device.
The [PKCS#11 Tech Note](https://www.pdf-tools.com/public/downloads/manuals/TechNotePKCS11.pdf) provides detailed information about configuring a PKCS#11 device to work with the Pdftools SDK.
Signing certificates can be loaded from the cryptographic device.
The certificate may be identified by using the certificate name, key ID or label.
Signing certificates can also be added using the `AddCertificate` method.
Additional certificates, for example, issuer certificates, are stored in the [Certificates directory](configure-digital-signing.mdx#storing-local-certificates).
These certificates are required when adding validation information to signatures that do not have the full trust chain embedded.
The [Certificates directory](configure-digital-signing.mdx#storing-local-certificates) may contain certificates in either PEM (.pem, ASCII text) or DER (.cer, binary) form.
In this example, the `Pkcs11` cryptographic provider is used to apply a document approval signature to a PDF document.
The signing certificate is loaded from the PKCS#11 device by passing a certificate name.
**Steps to sign a document**:
1. [Load the PKCS#11 driver module](#loading-the-pkcs11-driver-module).
2. [Log in to the PKCS#11 device](#logging-in-to-the-pkcs11-device).
3. [Create the document signature](#creating-the-document-signature).
4. [Open and sign the document](#opening-and-signing-the-document).
---
:::note Before you begin
You need to **[initialize the library](/docs/licenses/products/pdf-tools-sdk-license/#activate-the-pdftools-sdk-license)**.
:::
## Loading the PKCS#11 driver module
When using the `Pkcs11` cryptographic provider, you start the digital signing process by loading the PKCS#11 driver module.
The PKCS#11 driver module is used to connect to the cryptographic device, exposing the cryptographic functions of the device.
```csharp
// Load the PKCS#11 driver module (middleware)
// The module can only be loaded once in the application.
using var module = Pkcs11.Module.Load(moduleName);
```
```java
// Load the PKCS#11 driver module (middleware)
// The module can only be loaded once in the application.
Module module = Module.load(pkcs11Library);
```
## Logging in to the PKCS#11 device
The next step is to open a `Session` by logging into the cryptographic device using the driver module and a password.
The `Session` object provides access to the certificates and private keys stored on the device.
```csharp
// Create a session to the cryptographic device and log in
// with the password (pin)
using var session = module.Devices.GetSingle().CreateSession(password);
```
```java
// Create a session to the cryptographic device and log in
// with the password (PIN)
Session session = module.getDevices().getSingle().createSession(password));
```
## Creating the document signature
In this step, the `Session` object is used to create a signature configuration using a certificate stored on the device.
The signature configuration may be used to sign one or more documents.
In this example, a signing certificate is selected from the PKCS#11 device by passing a certificate name.
```csharp
// Create the signature configuration
// This can be re-used to sign multiple documents
var signature = session.CreateSignatureFromName(certificate);
```
```java
// Create the signature configuration
// This can be re-used to sign multiple documents
var signature = session.createSignatureFromName(certificate);
```
## Opening and signing the document
After opening the `Session` and creating the signature configuration, you are ready to apply the digital signature to a document.
The input and output PDF documents are created as streams (in this example, as file streams). The `Signer` object is used to apply the digital document signature.
Non-critical processing errors raise a `Warning` event. It is recommended to listen for these events, and review the `WarningCategory` to determine if further action is needed.
```csharp
// Open the input document
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);
// Create a stream for the output file
using var outStr = File.Create(outPath);
// Create the Signer object
Signer signer = new Signer();
// Create an event listener to listen for warning events that are raised and write them to console
signer.Warning += (s, e) => Console.WriteLine("Warning - {0}: {1}: {2}", e.Category, e.Context, e.Message);
// Sign the output document
using var outDoc = signer.Sign(inDoc, signature, outStr);
```
```java
// Open input document
FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
Document inDoc = Document.open(inStr);
// Create output stream
FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW);
// Create the Signer object
Signer signer = new Signer();
// (optional) Create an event listener to listen for warning events that are raised and write them to console
signer.addWarningListener((e) -> { System.out.format("Warning - %s: %s: %s", e.getCategory(), e.getContext(), e.getMessage()); });
// Sign the input document
Document outDoc = signer.sign(inDoc, signature, outStr);
```
## Full example
{/*sample source: PdfToolsSDK/Samples/Templates/pkcs11sign.cs*/}
```csharp
// Load the PKCS#11 driver module (middleware)
// The module can only be loaded once in the application.
using var module = Pkcs11.Module.Load(moduleName);
// Create a session to the cryptographic device and log in
// with the password (pin)
using var session = module.Devices.GetSingle().CreateSession(password);
// Create the signature configuration
// This can be re-used to sign multiple documents
var signature = session.CreateSignatureFromName(certificate);
// Open the input document
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);
// Create a stream for the output file
using var outStr = File.Create(outPath);
// Create the Signer object
Signer signer = new Signer();
// Create an event listener to listen for warning events that are raised and write them to console
signer.Warning += (s, e) => Console.WriteLine("Warning - {0}: {1}: {2}", e.Category, e.Context, e.Message);
// Sign the output document
using var outDoc = signer.Sign(inDoc, signature, outStr);
```
{/*sample source: PdfToolsSDK/Samples/Templates/pkcs11sign.java*/}
```java
try (
// Load the PKCS#11 driver module (middleware)
// The module can only be loaded once in the application.
Module module = Module.load(pkcs11Library);
// Create a session to the cryptographic device and log in
// with the password (pin)
Session session = module.getDevices().getSingle().createSession(password))
{
// Create the signature configuration
// This can be re-used to sign multiple documents
SignatureConfiguration signature = session.createSignatureFromName(certificate);
// Create the Signer object
Signer signer = new Signer();
// (optional) Create an event listener to listen for warning events that are raised and write them to console
signer.addWarningListener((e) -> { System.out.format("Warning - %s: %s: %s", e.getCategory(), e.getContext(), e.getMessage()); });
try (
// Open input document
FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
Document inDoc = Document.open(inStr);
// Create output stream
FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW);
// Sign the input document
Document outDoc = signer.sign(inDoc, signature, outStr))
{
}
}
```
---
## Swisscom cryptographic provider
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
The `SwisscomSigSrv` cryptographic provider enables access to the [Swisscom Signing Service](https://trustservices.swisscom.com/en/signing-service/). The service can then be used to perform cryptographic functions such as [sign a document](sign-document.mdx).
This provider requires a Swisscom Signing Service account.
Accounts with static and on-demand identities are supported.
:::tip Quick start with a code sample
Download the full sample now in **[C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/SwisscomSigSrvSign/Download?technology=CS)**, **[Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/SwisscomSigSrvSign/Download?technology=Java)**, **[Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/SwisscomSigSrvSign/Download?technology=Python)**, and **[Visual Basic](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/SwisscomSigSrvSign/Download?technology=VB)**.
Interested in C, Go, Rust or other programming language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.
:::
The Swisscom Signing Service provides signing certificates using CMS (PKCS#7) signatures.
Additional certificates (for example, issuer certificates) are stored in the [Certificates directory](configure-digital-signing.mdx#storing-local-certificates).
These certificates are required when adding validation information to signatures that do not have the full trust chain embedded.
The [Certificates directory](configure-digital-signing.mdx#storing-local-certificates) may contain certificates in either PEM (.pem, ASCII text) or DER (.cer, binary) form.
In this example, the `SwisscomSigSrv` cryptographic provider is used to apply a document approval signature to a PDF document.
The signing certificate is loaded from the Swisscom Signing Service using a static identity string provided by Swisscom.
Information required for long-term signature validation (LTV) is embedded in the output PDF.
**Steps to sign a document**:
1. [Configure the HTTP client handler](#configuring-the-http-client-handler).
2. [Connect to Swisscom Signing Service](#connecting-to-swisscom-signing-service).
3. [Create the document signature](#creating-the-document-signature).
4. [(Optional) Add long-term validation information](#adding-long-term-validation-information).
5. [Open and sign the document](#opening-and-signing-the-document).
---
:::note Before you begin
You need to **[initialize the library](/docs/licenses/products/pdf-tools-sdk-license/#activate-the-pdftools-sdk-license)**.
:::
## Configuring the HTTP client handler
When using the `SwisscomSigSrv` cryptographic provider, you need to configure the `HttpClientHandler` with the SSL client certificate and password from your Swisscom account.
```csharp
// Configure the SSL client certificate to connect to the Swisscom Signing Service
var httpClientHandler = new HttpClientHandler();
using (var sslClientCert = File.OpenRead(@"C:\path\to\clientcert.p12"))
httpClientHandler.SetClientCertificate(sslClientCert, password);
```
```java
// Configure the SSL client certificate to connect to the service
HttpClientHandler httpClientHandler = new HttpClientHandler();
try (FileStream sslClientCert = new FileStream("C:/path/to/clientcert.p12", FileStream.Mode.READ_ONLY))
{
httpClientHandler.setClientCertificate(sslClientCert, password);
}
```
## Connecting to Swisscom Signing Service
The next step is to open a `Session` to the Swisscom Signing Service.
The `Session` object provides access to the certificates and private keys stored by Swisscom.
In this example, the default URI for the Swisscom Signing Service is used.
```csharp
// Connect to the Swisscom Signing Service
using var session = new SwisscomSigSrv.Session(new Uri("https://ais.swisscom.com"), httpClientHandler);
```
```java
Session session = new Session(new URI("https://ais.swisscom.com"), httpClientHandler);
```
## Creating the document signature
In this step, the `Session` object is used to create a signature configuration for a Swisscom Signing Service account using a static identity string provided by Swisscom.
With a static identity, the common name is used for the signature appearance and for the signature description stored in the PDF document.
The signature configuration may be used to sign one or more documents.
:::tip
To sign with Mobile ID, you use the `CreateSignatureForDynamicIdentity` method and pass `StepUp` authorization parameters.
:::
```csharp
// Create a signing certificate for a static identity
var signature = session.CreateSignatureForStaticIdentity(identity, commonName);
```
```java
// Create a signing certificate for a static identity
// This can be re-used to sign multiple documents
SignatureConfiguration signature = session.createSignatureForStaticIdentity(identity, commonName);
```
## Adding long-term validation information
As an optional step, [long-term validation](long-term-validation.mdx) information can be added to the output document.
It embeds revocation information such as online certificate status response and certificate revocation lists.
Revocation information is provided by a validation service at the time of signing and acts as proof that the certificate was valid at the time of signing.
```csharp
// Embed validation information to enable the long term validation (LTV) of the signature (default)
signature.EmbedValidationInformation = true;
```
```java
// Embed validation information to enable the long-term validation (LTV) of the signature (default)
signature.setEmbedValidationInformation(true);
```
## Opening and signing the document
After opening the `Session` and creating the signature configuration, you are ready to apply the digital signature to a document.
The input and output PDF documents are created as streams (in this example, as file streams). The `Signer` object is used to apply the digital document signature.
Non-critical processing errors raise a `Warning` event. It is recommended to listen for these events, and review the `WarningCategory` to determine if further action is needed.
```csharp
// Open the input document
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);
// Create a stream for the output file
using var outStr = File.Create(outPath);
// Create the Signer object
Signer signer = new Signer();
// Create an event listener to listen for warning events that are raised and write them to console
signer.Warning += (s, e) => Console.WriteLine("Warning - {0}: {1}: {2}", e.Category, e.Context, e.Message);
// Sign the output document
using var outDoc = signer.Sign(inDoc, signature, outStr);
```
```java
// Open input document
FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
Document inDoc = Document.open(inStr);
// Create output stream
FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW);
// Create the Signer object
Signer signer = new Signer();
// (optional) Create an event listener to listen for warning events that are raised and write them to console
signer.addWarningListener((e) -> { System.out.format("Warning - %s: %s: %s", e.getCategory(), e.getContext(), e.getMessage()); });
// Sign the input document
Document outDoc = signer.sign(inDoc, signature, outStr);
```
## Full example
{/*sample source: PdfToolsSDK/Samples/Templates/swisscomsignsrvsign.cs*/}
```csharp
// Configure the SSL client certificate to connect to the Swisscom Signing Service
var httpClientHandler = new HttpClientHandler();
using (var sslClientCert = File.OpenRead(@"C:\path\to\clientcert.p12"))
httpClientHandler.SetClientCertificate(sslClientCert, password);
// Connect to the Swisscom Signing Service
using var session = new SwisscomSigSrv.Session(new Uri("https://ais.swisscom.com"), httpClientHandler);
// Create a signing certificate for a static identity
var signature = session.CreateSignatureForStaticIdentity(identity, commonName);
// Embed validation information to enable the long term validation (LTV) of the signature (default)
signature.EmbedValidationInformation = true;
// Open the input document
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);
// Create a stream for the output file
using var outStr = File.Create(outPath);
// Create the Signer object
Signer signer = new Signer();
// Create an event listener to listen for warning events that are raised and write them to console
signer.Warning += (s, e) => Console.WriteLine("Warning - {0}: {1}: {2}", e.Category, e.Context, e.Message);
// Sign the output document
using var outDoc = signer.Sign(inDoc, signature, outStr);
```
{/*sample source: PdfToolsSDK/Samples/Templates/swisscomsignsrvsign.java*/}
```java
// Configure the SSL client certificate to connect to the service
HttpClientHandler httpClientHandler = new HttpClientHandler();
try (FileStream sslClientCert = new FileStream("C:/path/to/clientcert.p12", FileStream.Mode.READ_ONLY))
{
httpClientHandler.setClientCertificate(sslClientCert, password);
}
// Connect to the Swisscom Signing Service
try (Session session = new Session(new URI("https://ais.swisscom.com"), httpClientHandler))
{
// Create a signing certificate for a static identity
// This can be re-used to sign multiple documents
SignatureConfiguration signature = session.createSignatureForStaticIdentity(identity, commonName);
// Embed validation information to enable the long-term validation (LTV) of the signature (default)
signature.setEmbedValidationInformation(true);
// Create the Signer object
Signer signer = new Signer();
// (optional) Create an event listener to listen for warning events that are raised and write them to console
signer.addWarningListener((e) -> { System.out.format("Warning - %s: %s: %s", e.getCategory(), e.getContext(), e.getMessage()); });
try (
// Open input document
FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
Document inDoc = Document.open(inStr);
// Create output stream
FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW);
// Sign the input document
Document outDoc = signer.sign(inDoc, signature, outStr))
{
}
}
```
---
## Certify a PDF document
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
The Pdftools SDK lets you apply a document certification signature, also known as a Modification Detection and Prevention (MDP) signature, to a PDF document.
This type of signature records the identity of the document author.
It also allows users to make specific changes to the document, such as filling form fields, without invalidating the signature.
There can be at most one document certification signature in a document, and it must be added before any other signatures are added to the document.
:::tip Quick start with a code sample
Download the full sample now in **[C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/BuiltInCertify/Download?technology=CS)**, **[Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/BuiltInCertify/Download?technology=Java)**, **[Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/BuiltInCertify/Download?technology=Python)**, and **[Visual Basic](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/BuiltInCertify/Download?technology=VB)**.
Interested in C, Go, Rust or other programming language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.:::
In this example, the [Built-in cryptographic provider](provider-builtin.mdx) is used to digitally certify a PDF document.
The permissions allow a user to fill form fields.
Any other changes to the document cause the signature to be rejected.
:::note
Any of the [cryptographic providers supported by the Pdftools SDK](cryptographic-providers.mdx) can be used to apply a document certification signature.
:::
**Steps to certify a document**:
1. [Initialize the cryptographic provider](#initializing-the-cryptographic-provider).
2. [Read the PFX or P12 certificate](#reading-the-pfx-or-p12-certificate).
3. [(Optional) Add long-term validation information](#adding-long-term-validation-information)
4. [(Optional) Add user modification permissions](#adding-user-modification-permissions)
5. [Open and sign the document](#opening-and-signing-the-document).
---
:::note Before you begin
You need to **[initialize the library](/docs/licenses/products/pdf-tools-sdk-license/#activate-the-pdftools-sdk-license)**.
:::
## Initializing the cryptographic provider
When using the [Built-in cryptographic provider](provider-builtin.mdx), you start the digital signing process by instantiating the `Provider` object.
The `Provider` object exposes the methods of the cryptographic provider.
The cryptographic provider manages certificates and private keys, and implements cryptographic algorithms.
```csharp
// Create a session to the built-in cryptographic provider
using var session = new BuiltIn.Provider();
```
```java
// Create a session to the built-in cryptographic provider
Provider session = new Provider();
```
## Reading the PFX or P12 certificate
Using the Built-in cryptographic provider, PFX certificate files can be loaded directly into the cryptographic provider from the file system.
The certificate file is opened as a stream and loaded into the provider to prepare it to apply a digital signature.
```csharp
// Create signature configuration from PFX (or P12) file
using var pfxStr = File.OpenRead(certificateFile);
var signature = session.CreateSignatureFromCertificate(pfxStr, password);
```
```java
// Create signature configuration from PFX (or P12) file
FileStream pfxStr = new FileStream(certificateFile, FileStream.Mode.READ_ONLY));
SignatureConfiguration signature = session.createSignatureFromCertificate(pfxStr, password);
```
## Adding long-term validation information
As an optional step, [long-term validation](long-term-validation.mdx) information can be added to the output document. It embeds revocation information such as online certificate status response and certificate revocation lists. Revocation information is provided by a validation service at the time of signing and acts as proof that the certificate was valid at the time of signing.
```csharp
// Embed validation information to enable the long-term validation (LTV) of the signature
signature.ValidationInformation = PdfTools.Crypto.ValidationInformation.EmbedInDocument;
```
```java
// Embed validation information to enable the long-term validation (LTV) of the signature
signature.setValidationInformation(com.pdftools.crypto.ValidationInformation.EMBED_IN_DOCUMENT);
```
## Adding user modification permissions
As an optional step, the author may permit users to make specific modifications to the document without the signature being revoked.
In this example, the user is permitted to fill form fields.
```csharp
// Assign Form Filling user permissions to the document
var permissions = new MdpPermissionOptions(MdpPermissions.FormFilling);
```
```java
// Assign form filling user permissions to the document
MdpPermissionOptions permissions = new MdpPermissionOptions(MdpPermissions.FORM_FILLING);
```
## Opening and signing the document
After instantiating the `Provider` and preparing the signature configuration, you are ready to digitally certify a document.
The input and output PDF documents are created as streams (in this example, as file streams). The `Signer` object is used to apply the digital certification.
Non-critical processing errors raise a `Warning` event. It is recommended to listen for these events, and review the `WarningCategory` to determine if further action is needed.
```csharp
// Open the input document
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);
// Create a stream for the output file
using var outStr = File.Create(outPath);
// Create the Signer object
Signer signer = new Signer();
// (optional) Create an event listener to listen for warning events that are raised and write them to console
signer.Warning += (s, e) => Console.WriteLine("Warning - {0}: {1}: {2}", e.Category, e.Context, e.Message);
// Certify the output document
using var outDoc = signer.Certify(inDoc, signature, outStr, permissions);
```
```java
// Open input document
FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
Document inDoc = Document.open(inStr);
// Create a stream for the output file
FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW);
// Create the Signer object
Signer signer = new Signer();
// (optional) Create an event listener to listen for warning events that are raised and write them to console
signer.addWarningListener((e) -> { System.out.format("Warning - %s: %s: %s", e.getCategory(), e.getContext(), e.getMessage()); });
// Sign the input document
Document outDoc = signer.certify(inDoc, signature, outStr, permissions);
```
## Full example
{/*sample source: PdfToolsSDK/Samples/Templates/builtincertify.cs*/}
```csharp
// Create a session to the built-in cryptographic provider
using var session = new PdfTools.Crypto.Providers.BuiltIn.Provider();
// Create signature configuration from PFX (or P12) file
using var pfxStr = File.OpenRead(certificateFile);
var signature = session.CreateSignatureFromCertificate(pfxStr, password);
// Embed validation information to enable the long-term validation (LTV) of the signature (default)
signature.ValidationInformation = PdfTools.Crypto.ValidationInformation.EmbedInDocument;
// Assign Form Filling user permissions to the document
var permissions = new MdpPermissionOptions(MdpPermissions.FormFilling);
// Open input document
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);
// Create stream for output file
using var outStr = File.Create(outPath);
// Create the Signer object
Signer signer = new Signer();
// Create an event listener to listen for warning events that are raised and write them to console
signer.Warning += (s, e) => Console.WriteLine("Warning - {0}: {1}: {2}", e.Category, e.Context, e.Message);
// Certify the output document
using var outDoc = signer.Certify(inDoc, signature, outStr, permissions);
```
{/*sample source: PdfToolsSDK/Samples/Templates/builtincertify.java*/}
```java
try (
// Create a session to the built-in cryptographic provider
Provider session = new Provider();
// Open certificate file
FileStream pfxStr = new FileStream(certificateFile, FileStream.Mode.READ_ONLY))
{
// Create signature configuration from PFX (or P12) file
SignatureConfiguration signature = session.createSignatureFromCertificate(pfxStr, password);
// Embed validation information to enable the long-term validation (LTV) of the signature (default)
signature.setValidationInformation(com.pdftools.crypto.ValidationInformation.EMBED_IN_DOCUMENT);
// Assign form filling user permissions to the document
MdpPermissionOptions permissions = new MdpPermissionOptions(MdpPermissions.FORM_FILLING);
// Create the Signer object
Signer signer = new Signer();
// (optional) create an event listener to listen for warning events that are raised and write them to console
signer.addWarningListener((e) -> { System.out.format("Warning - %s: %s: %s", e.getCategory(), e.getContext(), e.getMessage()); });
try (
// Open input document
FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
Document inDoc = Document.open(inStr);
// Create output stream
FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW);
// Certify the output document
Document outDoc = new signer.certify(inDoc, signature, outStr, permissions))
{
}
}
```
:::info Signature visual appearance
You can also apply a visual appearance to the signatures. For more information, see [Create a signature visual appearance](signature-appearance.mdx) page.
:::
:::note Signing PDF/A documents
During the [conversion process from PDF to PDF/A](../../archive/archive-pdf-pdfa.mdx), any signatures are removed from the file before it is converted to PDF/A for archiving.
Therefore, files that require archiving should be [archived to PDF/A format](../../archive/archive-pdf-pdfa.mdx) before any digital signatures are applied.
:::
---
## Sign a PDF document
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
The Pdftools SDK lets you apply a document approval signature to a PDF document.
This type of signature records the identity of the signer, and confirms that the content of the document has not changed after the signature is applied.
:::tip Quick start with a code sample
Download the full sample now in **[C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/BuiltInSign/Download?technology=C)**, **[C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/BuiltInSign/Download?technology=CS)**, **[Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/BuiltInSign/Download?technology=Java)**, **[Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/BuiltInSign/Download?technology=Python)**, and **[Visual Basic](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/BuiltInSign/Download?technology=VB)**.
Interested in Go, Rust or other programming language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.:::
:::
In this example, the [Built-in cryptographic provider](provider-builtin.mdx) is used to apply a document approval signature to a PDF document.
The PFX certificate is read from a local file.
Information required for long-term signature validation (LTV) is embedded in the output PDF.
:::note
Any of the [cryptographic providers supported by the Pdftools SDK](cryptographic-providers.mdx) can be used to apply a document approval signature.
:::
**Steps to sign a document**:
1. [Initialize the cryptographic provider](#initializing-the-cryptographic-provider).
2. [Read the PFX or P12 certificate](#reading-the-pfx-or-p12-certificate).
3. [(Optional) Add long-term validation information](#adding-long-term-validation-information)
4. [Open and sign the document](#opening-and-signing-the-document).
---
:::note Before you begin
You need to **[initialize the library](/docs/licenses/products/pdf-tools-sdk-license/#activate-the-pdftools-sdk-license)**.
:::
## Initializing the cryptographic provider
When using the [Built-in cryptographic provider](provider-builtin.mdx), you start the digital signing process by instantiating the `Provider` object.
The `Provider` object exposes the methods of the cryptographic provider.
The cryptographic provider manages certificates and private keys, and implements cryptographic algorithms.
```csharp
// Create a session to the built-in cryptographic provider
using var session = new BuiltIn.Provider();
```
```java
// Create a session to the built-in cryptographic provider
Provider session = new Provider();
```
## Reading the PFX or P12 certificate
Using the Built-in cryptographic provider, PFX certificate files can be loaded directly into the cryptographic provider from the file system.
The certificate file is opened as a stream and loaded into the provider to prepare it to apply a digital signature.
```csharp
// Create signature configuration from PFX (or P12) file
using var pfxStr = File.OpenRead(certificateFile);
var signature = session.CreateSignatureFromCertificate(pfxStr, password);
```
```java
// Create signature configuration from PFX (or P12) file
FileStream pfxStr = new FileStream(certificateFile, FileStream.Mode.READ_ONLY));
SignatureConfiguration signature = session.createSignatureFromCertificate(pfxStr, password);
```
## Adding long-term validation information
As an optional step, [long-term validation](long-term-validation.mdx) information can be added to the output document.
It embeds revocation information such as online certificate status response and certificate revocation lists.
Revocation information is provided by a validation service at the time of signing and acts as proof that the certificate was valid at the time of signing.
```csharp
// Embed validation information to enable the long-term validation (LTV) of the signature
signature.ValidationInformation = PdfTools.Crypto.ValidationInformation.EmbedInDocument;
```
```java
// Embed validation information to enable the long-term validation (LTV) of the signature (default)
signature.setValidationInformation(com.pdftools.crypto.ValidationInformation.EMBED_IN_DOCUMENT);
```
## Opening and signing the document
After instantiating the `Provider` and preparing the signature configuration, you are ready to apply the digital signature to a document.
The input and output PDF documents are created as streams (in this example, as file streams). The `Signer` object is used to apply the digital document signature.
Non-critical processing errors raise a `Warning` event.
It is recommended to listen for these events, and review the `WarningCategory` to determine if further action is needed.
```csharp
// Open the input document
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);
// Create a stream for the output file
using var outStr = File.Create(outPath);
// Create the Signer object
Signer signer = new Signer();
// (optional) Create an event listener to listen for warning events that are raised and write them to console
signer.Warning += (s, e) => Console.WriteLine("Warning - {0}: {1}: {2}", e.Category, e.Context, e.Message);
// Sign the output document
using var outDoc = signer.Sign(inDoc, signature, outStr);
```
```java
// Open input document
FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
Document inDoc = Document.open(inStr);
// Create a stream for the output file
FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW);
// Create the Signer object
Signer signer = new Signer();
// (optional) Create an event listener to listen for warning events that are raised and write them to console
signer.addWarningListener((e) -> { System.out.format("Warning - %s: %s: %s", e.getCategory(), e.getContext(), e.getMessage()); });
// Sign the input document
Document outDoc = signer.sign(inDoc, signature, outStr);
```
## Full example
{/*sample source: PdfToolsSDK/Samples/Templates/builtinsign.cs*/}
```csharp
// Create a session to the built-in cryptographic provider
using var session = new BuiltIn.Provider();
// Create signature configuration from PFX (or P12) file
using var pfxStr = File.OpenRead(certificateFile);
var signature = session.CreateSignatureFromCertificate(pfxStr, password);
// Embed validation information to enable the long-term validation (LTV) of the signature (default)
signature.ValidationInformation = PdfTools.Crypto.ValidationInformation.EmbedInDocument;
// Open input document
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);
// Create stream for output file
using var outStr = File.Create(outPath);
// Create the Signer object
Signer signer = new Signer();
// Create an event listener to listen for warning events that are raised and write them to console
signer.Warning += (s, e) => Console.WriteLine("Warning - {0}: {1}: {2}", e.Category, e.Context, e.Message);
// Sign the output document
using var outDoc = signer.Sign(inDoc, signature, outStr);
```
{/*sample source: PdfToolsSDK/Samples/Templates/builtinsign.java*/}
```java
try (
// Create a session to the built-in cryptographic provider
Provider session = new Provider();
// Open certificate file
FileStream pfxStr = new FileStream(certificateFile, FileStream.Mode.READ_ONLY))
{
// Create signature configuration from PFX (or P12) file
SignatureConfiguration signature = session.createSignatureFromCertificate(pfxStr, password);
// Embed validation information to enable the long-term validation (LTV) of the signature (default)
signature.setValidationInformation(com.pdftools.crypto.ValidationInformation.EMBED_IN_DOCUMENT);
// Create the Signer object
Signer signer = new Signer();
// (optional) create an event listener to listen for warning events that are raised and write them to console
signer.addWarningListener((e) -> { System.out.format("Warning - %s: %s: %s", e.getCategory(), e.getContext(), e.getMessage()); });
try (
// Open input document
FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
Document inDoc = Document.open(inStr);
// Create a stream for the output file
FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW);
// Sign the input document
Document outDoc = signer.sign(inDoc, signature, outStr))
{
}
}
```
:::important Signing PDF/A documents
During the [conversion process from PDF to PDF/A](../../archive/archive-pdf-pdfa.mdx), any signatures are removed from the file before it is converted to PDF/A for archiving.
Therefore, files that require archiving should be [archived to PDF/A format](../../archive/archive-pdf-pdfa.mdx) before any digital signatures are applied.
:::
---
## Add a document time-stamp
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
The Pdftools SDK lets you apply a time-stamp to a PDF document.
This type of digital signature provides evidence that a document existed at a specific time, and that the content of the document has not changed since that time.
:::tip Quick start with a code sample
Download the full sample now in **[C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/BuiltInAddTimestamp/Download?technology=CS)**, **[Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/BuiltInAddTimestamp/Download?technology=Java)**, **[Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/BuiltInAddTimestamp/Download?technology=Python)**, and **[Visual Basic](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/BuiltInAddTimestamp/Download?technology=VB)**.
Interested in Go, Rust or other programming language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.:::
:::
The time-stamp is provided by a [time-stamp authority](timestamp-authority.mdx) (TSA) that is configured in the cryptographic provider.
In this example, the [Built-In cryptographic provider](provider-builtin.mdx) is used to apply a time-stamp to a PDF document.
A third-party time-stamp authority is configured in the cryptographic provider.
**Steps to apply a digital time-stamp**:
1. [Initialize the cryptographic provider](#initializing-the-cryptographic-provider).
2. [Connect to the time-stamp authority](#connecting-to-the-time-stamp-authority).
3. [Add the document time-stamp](#adding-the-document-time-stamp).
---
:::note Before you begin
You need to **[initialize the library](/docs/licenses/products/pdf-tools-sdk-license/#activate-the-pdftools-sdk-license)**.
:::
## Initializing the cryptographic provider
When using the [Built-In cryptographic provider](provider-builtin.mdx), you start the document time-stamp process by instantiating the `Provider` object.
The `Provider` object exposes the methods of the cryptographic provider.
The cryptographic provider manages certificates and private keys, and implements cryptographic algorithms.
```csharp
// Create a session to the built-in cryptographic provider
using var session = new BuiltIn.Provider();
```
```java
// Create a session to the built-in cryptographic provider
Provider session = new Provider();
```
## Connecting to the time-stamp authority
For the [Built-In](../provider-builtin) and [PKCS#11](provider-pkcs11.mdx) cryptographic providers, a third-party time-stamp authority must be configured.
To do this, you pass [the URL of the time-stamp authority](timestamp-authority.mdx#time-stamp-authority-uri) to the cryptographic provider and call the `CreateTimestamp` method.
```csharp
// Create time-stamp configuration
session.TimestampUrl = timeStampUrl;
var timestamp = session.CreateTimestamp();
```
```java
// Create time-stamp configuration
session.setTimestampUrl(timeStampUrl);
TimestampConfiguration timestamp = session.createTimestamp();
```
## Adding the document time-stamp
After instantiating the `Provider` and preparing the time-stamp configuration, you are ready to apply the digital time-stamp to a document.
The input and output PDF documents are created as streams (in this example, as file streams).
The `Signer` object is used to apply the digital time-stamp.
Non-critical processing errors raise a `Warning` event. It is recommended to listen for these events, and review the `WarningCategory` to determine if further action is needed.
```csharp
// Open the input document
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);
// Create a stream for the output file
using var outStr = File.Create(outPath);
// Create the Signer object
Signer signer = new Signer();
// Create an event listener to listen for warning events that are raised and write them to console
signer.Warning += (s, e) => Console.WriteLine("Warning - {0}: {1}: {2}", e.Category, e.Context, e.Message);
// Add the document time-stamp
using var outDoc = new Signer().AddTimestamp(inDoc, timestamp, outStr);
```
```java
// Open input document
FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
Document inDoc = Document.open(inStr);
// Create a stream for the output file
FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW);
// Create the Signer object
Signer signer = new Signer();
// (optional) Create an event listener to listen for warning events that are raised and write them to console
signer.addWarningListener((e) -> { System.out.format("Warning - %s: %s: %s", e.getCategory(), e.getContext(), e.getMessage()); });
// Sign the input document
Document outDoc = signer.addTimestamp(inDoc, signature, outStr);
```
## Full example
{/*sample source: PdfToolsSDK/Samples/Templates/builtinaddtimestamp.cs*/}
```csharp
// Create a session to the built-in cryptographic provider
using var session = new BuiltIn.Provider();
// Create time-stamp configuration
session.TimestampUrl = timeStampUrl;
var timestamp = session.CreateTimestamp();
// Open input document
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);
// Create stream for output file
using var outStr = File.Create(outPath);
// Create the Signer object
Signer signer = new Signer();
// Create an event listener to listen for warning events that are raised and write them to console
signer.Warning += (s, e) => Console.WriteLine("Warning - {0}: {1}: {2}", e.Category, e.Context, e.Message);
// Add the document time-stamp
using var outDoc = signer.AddTimestamp(inDoc, timestamp, outStr);
```
{/*sample source: PdfToolsSDK/Samples/Templates/builtinaddtimestamp.java*/}
```java
// Create a session to the built-in cryptographic provider
try (Provider session = new Provider())
{
// Configure URL of the trusted time-stamp authority (TSA)
session.setTimestampUrl(timeStampUrl);
// Create time-stamp configuration
TimestampConfiguration timestamp = session.createTimestamp();
// Create the Signer object
Signer signer = new Signer();
// (optional) Create an event listener to listen for warning events that are raised and write them to console
signer.addWarningListener((e) -> { System.out.format("Warning - %s: %s: %s", e.getCategory(), e.getContext(), e.getMessage()); });
try (
// Open input document
FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
Document inDoc = Document.open(inStr);
// Create output stream
FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW);
// Add the document time-stamp
Document outDoc = signer.addTimestamp(inDoc, timestamp, outStr))
{
}
}
```
:::info Signature visual appearance
You can also apply a visual appearance to the signatures. For more information, see [Create a signature visual appearance](signature-appearance.mdx) page.
:::
:::note Signing PDF/A documents
During the [conversion process from PDF to PDF/A](../../archive/archive-pdf-pdfa.mdx), any signatures are removed from the file before it is converted to PDF/A for archival.
Therefore we recommend files that require archiving should be [archived to PDF/A format](../../archive/archive-pdf-pdfa.mdx) before any digital signatures are applied.
:::
---
## Validate signatures in a signed PDF document
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
The Pdftools SDK lets you validate digital signatures that have been added to [approve](sign-document.mdx) or [certify](sign-certify.mdx) a PDF document. The validation process can reference online and offline sources such as:
- Certificates, OCSP and CRL data embedded in the PDF file
- Certificates, OCSP and CRL data downloaded from online sources
- Certificates stored on the local file system
- Certificates stored in the system's default trust store
:::tip Quick start with a code sample
Download the full sample now in **[C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/SignaturesValidate/Download?technology=CS)**, **[Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/SignaturesValidate/Download?technology=Java)**, **[Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/SignaturesValidate/Download?technology=Python)**, and **[Visual Basic](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/SignaturesValidate/Download?technology=VB)**.
Interested in C, Go, Rust or other programming language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.:::
:::
This example shows how to validate a digital signature using certificate information embedded in the PDF file, and a Custom Trust List built from certificate files stored on the local file system.
**Steps to validate signatures in a document**:
1. [Create a validator object](#creating-a-validator-object).
2. [Configure the validation parameters](#configuring-the-validation-parameters).
3. [(Optional) Add certificates for offline validation](#adding-certificates-for-offline-validation).
4. [Open and validate the document](#opening-and-validating-the-document).
5. [Check and output the results](#checking-and-outputting-the-results)
---
:::note Before you begin
You need to **[initialize the library](/docs/licenses/products/pdf-tools-sdk-license/#activate-the-pdftools-sdk-license)**.
:::
## Creating a Validator object
The `Validator` object validates the signatures in the input PDF document against trusted sources.
It is used to process the signatures as defined in the [validation parameters](#configuring-the-validation-parameters) and calculate the overall validation result.
```csharp
// Create a Validator object
var validator = new Validator();
```
```java
// Create a Validator object
Validator validator = new Validator();
```
## Configuring the validation parameters
The validator object lets you configure the validation process to handle your business logic.
For example, you can validate all signatures in a document and use several trusted sources for signature validation.
To do this, you can use the `Default` profile and the `SignatureSelector.ALL`.
```csharp
// Use the default validation profile as a base for further settings
var profile = new Profiles.Default();
// Validate ALL signatures in the document (not only the latest)
var signatureSelector = SignatureSelector.All;
```
:::tip
You can adjust the validation settings to your specific business case using the profile's `ValidationOptions`, `SigningCertTrustConstraints`, and `TimeStampTrustConstraints`.
:::
```java
// Use the default validation profile as a base for further settings
Profile profile = new Default();
// Validate ALL signatures in the document (not only the latest)
SignatureSelector signatureSelector = SignatureSelector.ALL;
```
:::tip
You can adjust the validation settings to your specific business case using the profile's `getValidationOptions`, `getSigningCertTrustConstraints`, and `getTimeStampTrustConstraints`.
:::
## Adding certificates for offline validation
Certificate files (e.g. PFX or CER) from the local file system can be added as trusted sources using a `CustomTrustList`.
```csharp
// create a CustomTrustList to hold the certificates
var ctl = new CustomTrustList();
// Iterate through files in the certificate directory and add certificates
// to the custom trust list
if (Directory.Exists(certDir))
{
var directoryListing = Directory.EnumerateFiles(certDir);
foreach (string fileName in directoryListing)
{
try
{
using var certStr = File.OpenRead(fileName);
if (fileName.EndsWith(".cer") || fileName.EndsWith(".pem"))
{
ctl.AddCertificates(certStr);
}
else if (fileName.EndsWith(".p12") || fileName.EndsWith(".pfx"))
{
// If a password is required, use addArchive(certStr, password).
ctl.AddArchive(certStr);
}
}
catch (Exception e)
{
Console.WriteLine("Could not add certificate '" + fileName + "' to custom trust list: " + e.Message);
}
}
}
else
{
// Handle the case where dir is not a directory
Console.WriteLine("Directory " + certDir + " is missing. No certificates were added to the custom trust list.");
}
Console.WriteLine();
// Assign the custom trust list to the validation profile
profile.CustomTrustList = ctl;
// Allow validation from embedded file sources and the custom trust list
var vo = profile.ValidationOptions;
vo.TimeSource = TimeSource.ProofOfExistence | TimeSource.ExpiredTimeStamp | TimeSource.SignatureTime;
vo.CertificateSources = DataSource.EmbedInSignature | DataSource.EmbedInDocument | DataSource.CustomTrustList;
// Disable revocation checks.
profile.SigningCertTrustConstraints.RevocationCheckPolicy = RevocationCheckPolicy.NoCheck;
profile.TimeStampTrustConstraints.RevocationCheckPolicy = RevocationCheckPolicy.NoCheck;
```
```java
// create a CustomTrustList to hold the certificates
CustomTrustList ctl = new CustomTrustList();
// Iterate through files in the certificate directory and add certificates
// to the custom trust list
File dir = new File(certDir);
File[] directoryListing = dir.listFiles();
if (directoryListing != null)
{
for (File child : directoryListing)
{
String fileName = child.getName();
try (
FileStream certStr = new FileStream(child.getPath(), FileStream.Mode.READ_ONLY))
{
if (fileName.endsWith(".cer") || fileName.endsWith(".pem"))
{
ctl.addCertificates(certStr);
}
else if (fileName.endsWith(".p12") || fileName.endsWith(".pfx"))
{
// If a password is required, use addArchive(certStr, password).
ctl.addArchive(certStr);
}
}
catch (Exception e)
{
System.out.println("Could not add certificate '" + child.getName() + "' to custom trust list: " + e.getMessage());
}
}
}
else
{
// Handle the case where dir is not a directory
System.out.println("Directory " + certDir + " is missing. No certificates were added to the custom trust list.");
}
System.out.println();
// Assign the custom trust list to the validation profile
profile.setCustomTrustList(ctl);
// Allow validation from embedded file sources and the custom trust list
ValidationOptions vo = profile.getValidationOptions();
vo.setTimeSource(EnumSet.of(TimeSource.PROOF_OF_EXISTENCE, TimeSource.EXPIRED_TIME_STAMP, TimeSource.SIGNATURE_TIME));
vo.setCertificateSources(EnumSet.of(DataSource.EMBED_IN_SIGNATURE, DataSource.EMBED_IN_DOCUMENT, DataSource.CUSTOM_TRUST_LIST));
// Disable revocation checks.
profile.getSigningCertTrustConstraints().setRevocationCheckPolicy(RevocationCheckPolicy.NO_CHECK);
profile.getTimeStampTrustConstraints().setRevocationCheckPolicy(RevocationCheckPolicy.NO_CHECK);
```
:::tip
If you are using a Java `KeyStore` that has already been loaded, e.g. `ks`, you can use a `MemoryStream` to add the certificate to the `CustomTrustList`.
```java
// Create an OutputStream to write the KeyStore to (into memory)
ByteArrayOutputStream os = new ByteArrayOutputStream();
// Write the KeyStore to the OutputStream
ks.store(os, password.toCharArray());
// Put the OutputStream bytes into a MemoryStream
Stream certStr = new MemoryStream(os.toByteArray());
// Create a CustomTrustList to hold the certificates
CustomTrustList ctl = new CustomTrustList();
// Add the MemoryStream to the CustomTrustList
ctl.addArchive(certStr, password);
```
The `KeyStore` must be of type `PKCS12`.
For more information on the `KeyStore` please refer to the [Java API Reference](https://docs.oracle.com/javase/8/docs/api/java/security/KeyStore.html).
:::
## Opening and validating the document
After instantiating the validator object and configuring the validation profile, you are ready to validate the digital signatures in a document.
The input document is created as a stream (in this example, as file streams). The validator object is used to validate the digital signatures.
```csharp
using var inStr = File.OpenRead(inputFile);
// Open input document
// If a password is required, use Open(inStr, password)
using var document = Document.Open(inStr);
// Run the validate method passing the document, profile, and selector
var results = validator.Validate(document, profile, signatureSelector);
```
```java
FileStream inStr = new FileStream(inputFile, FileStream.Mode.READ_ONLY);
// Open input document
// If a password is required, use open(inStr, password)
Document document = Document.open(inStr);
// Run the validate method passing the document, profile, and selector
ValidationResults results = validator.validate(document, profile, signatureSelector);
```
## Checking and outputting the results
### Checking validation results
When validation is completed, the validator object returns a `ValidationResults` object that contains all the information obtained during the validation process.
This list contains a `ValidationResult` object for each signature with all the required information needed to build custom business logic.
In this example, all available information is printed to the console.
```csharp
// Print results
foreach (var result in results)
{
var field = result.SignatureField;
Console.WriteLine(field.FieldName + " of " + field.Name);
try
{
Console.WriteLine(" - Revision : " + (field.Revision.IsLatest ? "latest" : "intermediate"));
}
catch (Exception ex)
{
Console.WriteLine("Unable to validate document Revision: " + ex.Message);
}
PrintContent(result.SignatureContent);
Console.WriteLine();
}
```
:::note
To implement `PrintContent`, see [print and to string functions](#print-and-to-string-functions).
:::
```java
// Print results
results.forEach(result -> {
SignedSignatureField field = result.getSignatureField();
System.out.println(field.getFieldName() + " of " + field.getName());
try
{
System.out.println(" - Revision : " + (field.getRevision().getIsLatest() ? "latest" : "intermediate"));
}
catch (Exception ex)
{
System.out.println("Unable to validate document Revision: " + ex.getMessage());
}
printContent(result.getSignatureContent());
System.out.println();
});
```
:::note
To implement `printContent`, see [print and to string functions](#print-and-to-string-functions).
:::
### Checking constraint events
In addition to the validation results, the validator object raises constraint events for each signature `Constraint` checked.
A handler function can listen to these events to track the progress of the validation process. This way, you can link any errors to the signature causing the issue.
In this example, a simple console printer is used to output the signature information.
```csharp
validator.Constraint += (s, e) =>
{
Console.WriteLine(" - " + e.Signature.Name + (e.DataPart.Length > 0 ? (": " + e.DataPart) : "") + ": " +
ConstraintToString(e.Indication, e.SubIndication, e.Message));
};
```
:::note
To implement `ConstraintToString`, see [print and to string functions](#print-and-to-string-functions).
:::
```java
validator.addConstraintListener(e -> {
System.out.println(" - " + e.getSignature().getName() + (e.getDataPart().length() > 0 ? (": " + e.getDataPart()) : "") + ": " +
constraintToString(e.getIndication(), e.getSubIndication(), e.getMessage()));
});
```
:::note
To implement `constraintToString`, see [print and to string functions](#print-and-to-string-functions).
:::
## Full example
{/*sample source: PdfToolsSDK/Samples/Templates/signaturesvalidate.cs*/}
```csharp
// Use the default validation profile as a base for further settings
var profile = new Default();
// For offline operation, build a custom trust list from the file system
// and disable external revocation checks
if (certDir != null && certDir.Length != 0)
{
Console.WriteLine("Using 'offline' validation mode with custom trust list.");
Console.WriteLine();
// create a CustomTrustList to hold the certificates
var ctl = new CustomTrustList();
// Iterate through files in the certificate directory and add certificates
// to the custom trust list
if (Directory.Exists(certDir))
{
var directoryListing = Directory.EnumerateFiles(certDir);
foreach (string fileName in directoryListing)
{
try
{
using var certStr = File.OpenRead(fileName);
if (fileName.EndsWith(".cer") || fileName.EndsWith(".pem"))
{
ctl.AddCertificates(certStr);
}
else if (fileName.EndsWith(".p12") || fileName.EndsWith(".pfx"))
{
// If a password is required, use addArchive(certStr, password).
ctl.AddArchive(certStr);
}
}
catch (Exception e)
{
Console.WriteLine("Could not add certificate '" + fileName + "' to custom trust list: " + e.Message);
}
}
}
else
{
// Handle the case where dir is not a directory
Console.WriteLine("Directory " + certDir + " is missing. No certificates were added to the custom trust list.");
}
Console.WriteLine();
// Assign the custom trust list to the validation profile
profile.CustomTrustList = ctl;
// Allow validation from embedded file sources and the custom trust list
var vo = profile.ValidationOptions;
vo.TimeSource = TimeSource.ProofOfExistence | TimeSource.ExpiredTimeStamp | TimeSource.SignatureTime;
vo.CertificateSources = DataSource.EmbedInSignature | DataSource.EmbedInDocument | DataSource.CustomTrustList;
// Disable revocation checks.
profile.SigningCertTrustConstraints.RevocationCheckPolicy = RevocationCheckPolicy.NoCheck;
profile.TimeStampTrustConstraints.RevocationCheckPolicy = RevocationCheckPolicy.NoCheck;
}
// Validate ALL signatures in the document (not only the latest)
var signatureSelector = SignatureSelector.All;
// Create the validator object and event listeners
var validator = new Validator();
validator.Constraint += (s, e) =>
{
Console.WriteLine(" - " + e.Signature.Name + (e.DataPart.Length > 0 ? (": " + e.DataPart) : "") + ": " +
ConstraintToString(e.Indication, e.SubIndication, e.Message));
};
try
{
using var inStr = File.OpenRead(inputFile);
// Open input document
// If a password is required, use Open(inStr, password)
using var document = Document.Open(inStr);
// Run the validate method passing the document, profile and selector
Console.WriteLine("Validation Constraints");
var results = validator.Validate(document, profile, signatureSelector);
Console.WriteLine();
Console.WriteLine("Signatures validated: " + results.Count);
Console.WriteLine();
// Print results
foreach (var result in results)
{
var field = result.SignatureField;
Console.WriteLine(field.FieldName + " of " + field.Name);
try
{
Console.WriteLine(" - Revision : " + (field.Revision.IsLatest ? "latest" : "intermediate"));
}
catch (Exception ex)
{
Console.WriteLine("Unable to validate document Revision: " + ex.Message);
}
PrintContent(result.SignatureContent);
Console.WriteLine();
}
return 0;
}
catch (Exception ex)
{
Console.WriteLine("Unable to validate file: " + ex.Message);
return 5;
}
```
{/*sample source: PdfToolsSDK/Samples/Templates/signaturesvalidate.java*/}
```java
// Use the default validation profile as a base for further settings
Profile profile = new Default();
// For offline operation, build a custom trust list from the file system
// and disable external revocation checks
if (certDir != null && !certDir.isEmpty())
{
System.out.println("Using 'offline' validation mode with custom trust list.");
System.out.println();
// create a CustomTrustList to hold the certificates
CustomTrustList ctl = new CustomTrustList();
// Iterate through files in the certificate directory and add certificates
// to the custom trust list
File dir = new File(certDir);
File[] directoryListing = dir.listFiles();
if (directoryListing != null)
{
for (File child : directoryListing)
{
String fileName = child.getName();
try (
FileStream certStr = new FileStream(child.getPath(), FileStream.Mode.READ_ONLY))
{
if (fileName.endsWith(".cer") || fileName.endsWith(".pem"))
{
ctl.addCertificates(certStr);
}
else if (fileName.endsWith(".p12") || fileName.endsWith(".pfx"))
{
// If a password is required, use addArchive(certStr, password).
ctl.addArchive(certStr);
}
}
catch (Exception e)
{
System.out.println("Could not add certificate '" + child.getName() + "' to custom trust list: " + e.getMessage());
}
}
}
else
{
// Handle the case where dir is not a directory
System.out.println("Directory " + certDir + " is missing. No certificates were added to the custom trust list.");
}
System.out.println();
// Assign the custom trust list to the validation profile
profile.setCustomTrustList(ctl);
// Allow validation from embedded file sources and the custom trust list
ValidationOptions vo = profile.getValidationOptions();
vo.setTimeSource(EnumSet.of(TimeSource.PROOF_OF_EXISTENCE, TimeSource.EXPIRED_TIME_STAMP, TimeSource.SIGNATURE_TIME));
vo.setCertificateSources(EnumSet.of(DataSource.EMBED_IN_SIGNATURE, DataSource.EMBED_IN_DOCUMENT, DataSource.CUSTOM_TRUST_LIST));
// Disable revocation checks.
profile.getSigningCertTrustConstraints().setRevocationCheckPolicy(RevocationCheckPolicy.NO_CHECK);
profile.getTimeStampTrustConstraints().setRevocationCheckPolicy(RevocationCheckPolicy.NO_CHECK);
}
// Validate ALL signatures in the document (not only the latest)
SignatureSelector signatureSelector = SignatureSelector.ALL;
// Create the validator object and event listeners
Validator validator = new Validator();
validator.addConstraintListener(e -> {
System.out.println(" - " + e.getSignature().getName() + (e.getDataPart().length() > 0 ? (": " + e.getDataPart()) : "") + ": " +
constraintToString(e.getIndication(), e.getSubIndication(), e.getMessage()));
});
try (
FileStream inStr = new FileStream(inputFile, FileStream.Mode.READ_ONLY);
// Open input document
// If a password is required, use open(inStr, password)
Document document = Document.open(inStr);
)
{
// Run the validate method passing the document, profile and selector
System.out.println("Validation Constraints");
ValidationResults results = validator.validate(document, profile, signatureSelector);
System.out.println();
System.out.println("Signatures validated: " + results.size());
System.out.println();
// Print results
results.forEach(result -> {
SignedSignatureField field = result.getSignatureField();
System.out.println(field.getFieldName() + " of " + field.getName());
try
{
System.out.println(" - Revision : " + (field.getRevision().getIsLatest() ? "latest" : "intermediate"));
}
catch (Exception ex)
{
System.out.println("Unable to validate document Revision: " + ex.getMessage());
}
printContent(result.getSignatureContent());
System.out.println();
});
return 0;
}
catch (Exception ex)
{
System.out.println("Unable to validate file: " + ex.getMessage());
return 5;
}
```
#### Print and to string functions
The following print and to string functions let you list all the properties of the signatures and the signature results.
For example, you can use `PrintContent` to print certification details such as subject, issuer, and validity.
Using `ConstraintsToString`, you can convert a constraint to a string representation.
```csharp
// Helper functions to print signature validation details
private static void PrintContent(SignatureContent content)
{
if(content != null)
{
Console.WriteLine(" - Validity : " + ConstraintToString(content.Validity));
switch (content)
{
case UnsupportedSignatureContent:
break;
case CmsSignatureContent signature:
{
Console.WriteLine(" - Validation: " + signature.ValidationTime + " from " + signature.ValidationTimeSource);
Console.WriteLine(" - Hash : " + signature.HashAlgorithm);
Console.WriteLine(" - Signing Cert");
PrintContent(signature.SigningCertificate);
Console.WriteLine(" - Chain");
foreach (var cert in signature.CertificateChain)
{
Console.WriteLine(" - Issuer Cert " + (signature.CertificateChain.IndexOf(cert) + 1));
PrintContent(cert);
}
Console.WriteLine(" - Chain : " + (signature.CertificateChain.IsComplete ? "complete" : "incomplete") + " chain");
Console.WriteLine(" Time-Stamp");
PrintContent(signature.TimeStamp);
break;
}
case TimeStampContent timeStamp:
{
Console.WriteLine(" - Validation: " + timeStamp.ValidationTime + " from " + timeStamp.ValidationTimeSource);
Console.WriteLine(" - Hash : " + timeStamp.HashAlgorithm);
Console.WriteLine(" - Time : " + timeStamp.Date);
Console.WriteLine(" - Signing Cert");
PrintContent(timeStamp.SigningCertificate);
Console.WriteLine(" - Chain");
foreach (var cert in timeStamp.CertificateChain)
{
Console.WriteLine(" - Issuer Cert " + (timeStamp.CertificateChain.IndexOf(cert) + 1));
PrintContent(cert);
}
Console.WriteLine(" - Chain : " + (timeStamp.CertificateChain.IsComplete ? "complete" : "incomplete") + " chain");
break;
}
default:
Console.WriteLine("Unsupported signature content type " + content.GetType().Name);
break;
}
}
else
{
Console.WriteLine(" - null");
}
}
private static void PrintContent(Certificate cert)
{
if(cert != null)
{
Console.WriteLine(" - Subject : " + cert.SubjectName);
Console.WriteLine(" - Issuer : " + cert.IssuerName);
Console.WriteLine(" - Validity : " + cert.NotBefore + " - " + cert.NotAfter);
try
{
Console.WriteLine(" - Fingerprint: " + FormatSha1Digest(new BigInteger(SHA1.Create().ComputeHash(cert.RawData)).ToByteArray(), "-"));
}
catch (Exception ex)
{
Console.WriteLine(ex.Message);
}
Console.WriteLine(" - Source : " + cert.Source);
Console.WriteLine(" - Validity : " + ConstraintToString(cert.Validity));
}
else
{
Console.WriteLine(" - null");
}
}
private static String ConstraintToString(ConstraintResult constraint)
{
return ConstraintToString(constraint.Indication, constraint.SubIndication, constraint.Message);
}
private static String ConstraintToString(Indication indication, SubIndication subIndication, String message)
{
return (indication == Indication.Valid ? "" : (indication == Indication.Indeterminate ? "?" : "!")) + "" +
subIndication + " " +
message;
}
// Helper function to generate a delimited SHA-1 digest string
private static String FormatSha1Digest(byte[] bytes, String delimiter)
{
var result = new StringBuilder();
foreach (byte aByte in bytes)
{
int number = (int)aByte & 0xff;
String hex = number.ToString("X2");
result.Append(hex.ToUpper() + delimiter);
}
return result.ToString().Substring(0, result.Length - delimiter.Length);
}
```
For example, you can use `printContent` to print certification details such as subject, issuer, and validity.
Using `constraintsToString`, you can convert a constraint to a string representation.
```java
// Helper functions to print signature validation details
private static void printContent(SignatureContent content)
{
if(content != null)
{
System.out.println(" - Validity : " + constraintToString(content.getValidity()));
switch (content.getClass().getSimpleName())
{
case "UnsupportedSignatureContent":
break;
case "CmsSignatureContent":
{
CmsSignatureContent signature = (CmsSignatureContent)content;
System.out.println(" - Validation: " + signature.getValidationTime() + " from " + signature.getValidationTimeSource());
System.out.println(" - Hash : " + signature.getHashAlgorithm());
System.out.println(" - Signing Cert");
printContent(signature.getSigningCertificate());
System.out.println(" - Chain");
signature.getCertificateChain().forEach(cert -> {
System.out.println(" - Issuer Cert " + (signature.getCertificateChain().indexOf(cert) + 1));
printContent(cert);
});
System.out.println(" - Chain : " + (signature.getCertificateChain().getIsComplete() ? "complete" : "incomplete") + " chain");
System.out.println(" Time-Stamp");
printContent(signature.getTimeStamp());
break;
}
case "TimeStampContent":
{
TimeStampContent timeStamp = (TimeStampContent)content;
System.out.println(" - Validation: " + timeStamp.getValidationTime() + " from " + timeStamp.getValidationTimeSource());
System.out.println(" - Hash : " + timeStamp.getHashAlgorithm());
System.out.println(" - Time : " + timeStamp.getDate());
System.out.println(" - Signing Cert");
printContent(timeStamp.getSigningCertificate());
System.out.println(" - Chain");
timeStamp.getCertificateChain().forEach(cert -> {
System.out.println(" - Issuer Cert " + (timeStamp.getCertificateChain().indexOf(cert) + 1));
printContent(cert);
});
System.out.println(" - Chain : " + (timeStamp.getCertificateChain().getIsComplete() ? "complete" : "incomplete") + " chain");
break;
}
default:
System.out.println("Unsupported signature content type " + content.getClass().getName());
break;
}
}
else
{
System.out.println(" - null");
}
}
private static void printContent(Certificate cert)
{
if(cert != null)
{
System.out.println(" - Subject : " + cert.getSubjectName());
System.out.println(" - Issuer : " + cert.getIssuerName());
System.out.println(" - Validity : " + cert.getNotBefore() + " - " + cert.getNotAfter());
try {
System.out.println(" - Fingerprint: " + formatSha1Digest(new java.math.BigInteger(1, (MessageDigest.getInstance("SHA-1").digest(cert.getRawData()))).toByteArray(), "-"));
} catch (Exception ex) {
System.out.println(ex.getMessage());
}
System.out.println(" - Source : " + cert.getSource());
System.out.println(" - Validity : " + constraintToString(cert.getValidity()));
}
else
{
System.out.println(" - null");
}
}
private static String constraintToString(ConstraintResult constraint)
{
return constraintToString(constraint.getIndication(), constraint.getSubIndication(), constraint.getMessage());
}
private static String constraintToString(Indication indication, SubIndication subIndication, String message)
{
return (indication == Indication.VALID ? "" : (indication == Indication.INDETERMINATE ? "?" : "!")) + "" +
subIndication + " " +
message;
}
// Helper function to generate a delimited SHA-1 digest string
private static String formatSha1Digest(byte[] bytes, String delimiter) {
StringBuilder result = new StringBuilder();
for (byte aByte : bytes) {
int decimal = (int) aByte & 0xff;
String hex = Integer.toHexString(decimal);
if (hex.length() % 2 == 1)
hex = "0" + hex;
result.append(hex.toUpperCase() + delimiter);
}
return result.substring(0, result.length() - delimiter.length());
}
```
---
## Create a signature visual appearance
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
A signature can have a visual appearance on a PDF document page.
For example, the signature can appear as a company stamp or an individual's handwritten signature.
The Pdftools SDK lets you configure a visual appearance using an XML or a JSON file. The visual appearance can contain text, images, and pages of PDFs.
:::tip Quick start with a code sample
Download the full sample now in **[C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/VisualSignature/Download?technology=CS)**, **[Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/VisualSignature/Download?technology=Java)**, **[Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/VisualSignature/Download?technology=Python)**, and **[Visual Basic](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/VisualSignature/Download?technology=VB)**.
Interested in C, Go, Rust or other programming language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.
:::
:::info
The Pdftools SDK creates invisible signatures by default, because a signature's visual appearance can obscure important content on the page. The validity of the signature is not affected by its visual appearance.
:::
**Steps to add a signature visual appearance**:
1. [Configure visual appearance](#configure-visual-appearance)
2. [Apply text variables](#apply-text-variables)
- [Pre-defined text variables](#pre-defined-text-variables)
- [Custom text variables](#custom-text-variables)
3. [Create a signature and set its visual appearance](#create-a-signature-and-set-its-visual-appearance)
4. [Create a signature visual appearance for an existing signature field](#create-a-signature-visual-appearance-for-an-existing-signature-field)
---
## Configure visual appearance
Configure the signature visual appearance either in an XML file or in a JSON file. The appearance comprises multiple text elements, images, or pages of PDFs that are placed inside the surrounding visual appearance container.
Examples:
```xml
Signed by: Max Muster
Signing date: [signature:date,localtime,%d.%m.%Y %H:%M:%S]
Company: [custom:company]
Powered by:
```
```json
{
"size": "130pt 90pt",
"content": [
{
"image": "DigitalSignature.jpg"
},
{
"pdf": "butterfly.pdf",
"margin-left": "110pt",
"width": "12pt",
"height": "12pt",
"margin-top": "5pt"
},
{
"image": "pdftools-icon.png",
"margin-left": "114pt",
"width": "8pt",
"margin-top": "79pt"
},
{
"margin-top": "20pt",
"margin-left": "1pt",
"text-align": "left",
"font-size": "10",
"text": [
"Signed by: ",
{
"color": "1 0.2 0",
"font": "Bell MT Bold",
"text-mode": "stroke",
"text": "Max Muster"
}
]
},
{
"margin-top": "43pt",
"margin-left": "1pt",
"text-align": "left",
"font-size": "6",
"text": [
"Signing date: ",
{
"font": "Courier",
"color": "0.2 0.2 0.2",
"text": "[signature:date,localtime,%d.%m.%Y %H:%M:%S]"
}
]
},
{
"margin-top": "55pt",
"margin-left": "1pt",
"text-align": "left",
"font-size": "6",
"text": [
"Company: ",
{
"font": "OpenSans-Semibold.ttf",
"color": "0 0 1",
"text": "[custom:company]"
}
]
},
{
"font-size": "4",
"font": "Arial",
"margin-top": "78pt",
"margin-left": "90pt",
"text": [ "Powered by:" ]
}
]
}
```
:::note
The XML or JSON file specifies only the size of the visual appearance container but not its actual location. In the case of [signing](#create-a-signature-and-set-its-visual-appearance), the location can be explicitly specified in the code, while for [signing of an existing unsigned signature field](#create-a-signature-visual-appearance-for-an-existing-signature-field), the location is predetermined.
:::
:::note General definition of XML schema file
The [schema file](pathname:///files/pdf-tools-sdk/schema-visual-appearance-version1.0.xsd) defines the visual appearance of an XML file. The structure of a JSON file is equivalent.
:::
The Pdftools SDK creates the appearance according to the configuration as follows:
```csharp
// Create appearance from an XML
using var appStream = File.OpenRead(appearanceXml);
Appearance appearance = Appearance.CreateFromXml(appStream);
```
```csharp
// Create appearance from a JSON file
using var appStream = File.OpenRead(appearanceJson);
Appearance appearance = Appearance.CreateFromJson(appStream);
```
```java
try (
// Create appearance from an XML
FileStream appConfigStr = new FileStream(appearanceXml, FileStream.Mode.READ_ONLY))
{
Appearance appearance = Appearance.createFromXml(appConfigStr));
}
```
```java
try (
// Create appearance from a JSON file
FileStream appConfigStr = new FileStream(appearanceJson, FileStream.Mode.READ_ONLY))
{
Appearance appearance = Appearance.createFromJson(appConfigStr);
}
```
## Apply text variables
Text variables are placeholders in the text. Placeholders are substituted with specific values just before signing the document. There are two types of text variables:
- Pre-defined variables (such as location, title, author)
- Custom variables (defined by you)
In other words, the text can be parametrized using text variables, either by pre-defined text variables or by custom text variables.
Text variables take the general form of `[:]`.
They are replaced by their actual values just before signing the document.
### Pre-defined text variables
There are a couple of pre-defined text variables for which values are set during code execution:
- `[signature:contactinfo]`
- `[signature:location]`
- `[signature:reason]`
- `[document:title]`
- `[document:author]`
- `[document:subject]`
The special variable `[signature:date,,]` describes the signing date. `` takes the values `utc` or `localtime`. Different date formats `` can be specified. Some typical formats are:
- EU: `%d.%m.%Y %H:%M:%S`
- US: `%m/%d/%Y %H:%M:%S`
- UK: `%d/%m/%Y %H:%M:%S`
For a complete description of the date formatting options consult https://strftime.org/.
### Custom text variables
You can also store custom text variables and their values as key-value pairs in the map `Appearance.CustomTextVariables`. For more information, see an example in [Create a signature and set visual appearance](#create-a-signature-and-set-its-visual-appearance) section. The `value` is accessed in the text by `[custom:]`.
## Create a signature and set its visual appearance
:::tip Get started
Learn more about [signing a PDF document](sign-document.mdx).
:::
```csharp
// Create a session to the built-in cryptographic provider
using var session = new BuiltIn.Provider();
// Open certificate file
using var pfxStr = File.OpenRead(certificateFile);
// Create signature configuration from PFX (or P12) file
SignatureConfiguration signature = session.CreateSignatureFromCertificate(pfxStr, password);
// Create appearance from either an XML or a JSON file
using var appStream = File.OpenRead(appConfigFile);
if (Path.GetExtension(appConfigFile) == ".xml")
signature.Appearance = Appearance.CreateFromXml(appStream);
else
signature.Appearance = Appearance.CreateFromJson(appStream);
signature.Appearance.PageNumber = 1;
signature.Appearance.CustomTextVariables.Add("company", "Daily Planet");
// Set location of appearance
signature.Appearance.Bottom = Length.pt(20);
signature.Appearance.Right = Length.pt(15);
// Open input document
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);
// Create stream for output file
using var outStr = File.Create(outPath);
// Sign the input document
using var outDoc = new Signer().Sign(inDoc, signature, outStr);
```
```java
try (
// Create a session to the built-in cryptographic provider
Provider session = new Provider();
// Open certificate file
FileStream pfxStr = new FileStream(certificateFile, FileStream.Mode.READ_ONLY))
{
// Create signature configuration from PFX (or P12) file
SignatureConfiguration signature = session.createSignatureFromCertificate(pfxStr, password);
try (
// Create appearance from either an XML or a JSON file
FileStream appConfigStr = new FileStream(appConfigFile, FileStream.Mode.READ_ONLY))
{
if (appConfigFile.toLowerCase().endsWith(".xml"))
signature.setAppearance(Appearance.createFromXml(appConfigStr));
else
signature.setAppearance(Appearance.createFromJson(appConfigStr));
signature.getAppearance().setPageNumber(1);
signature.getAppearance().getCustomTextVariables().put("company", "Daily Planet");
// Set location of appearance
signature.getAppearance().setBottom(new Length(20));
signature.getAppearance().setTop(new Length(15));
try(
// Open input document
FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
Document inDoc = Document.open(inStr);
// Create a stream for the output file
FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW);
// Sign the input document
Document outDoc = new Signer().sign(inDoc, signature, outStr))
{
}
}
}
```
## Create a signature visual appearance for an existing signature field
:::tip Get started
Learn more about [signing a PDF document](sign-document.mdx).
:::
You can apply a signature visual appearance when signing an existing unsigned signature field. In the following example, the input PDF's first unsigned signature field (of potentially many unsigned signature fields) is signed, and a visual appearance is added.
```csharp
// Create a session to the built-in cryptographic provider
using var session = new PdfTools.Crypto.Providers.BuiltIn.Provider();
// Create signature configuration from PFX (or P12) file
using var pfxStr = File.OpenRead(certificateFile);
Signature signature = session.CreateSignatureFromCertificate(pfxStr, password);
// Open input document
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);
// Choose first signature field
foreach (var field in inDoc.SignatureFields)
{
if (field != null)
{
signature.FieldName = field.FieldName;
break;
}
}
// Create stream for output file
using var outStr = File.Create(outPath);
// Create appearance from either an XML or a JSON file
using var appStream = File.OpenRead(appConfigFile);
if (Path.GetExtension(appConfigFile) == ".xml")
signature.Appearance = Appearance.CreateFromXml(appStream);
else
signature.Appearance = Appearance.CreateFromJson(appStream);
signature.Appearance.CustomTextVariables.Add("company", "Daily Planet");
// Sign the input document
using var outDoc = new Signer().Sign(inDoc, signature, outStr);
```
```java
try (
// Create a session to the built-in cryptographic provider
Provider session = new Provider();
// Open certificate file
FileStream pfxStr = new FileStream(certificateFile, FileStream.Mode.READ_ONLY);
// Open input document
FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
Document inDoc = Document.open(inStr);)
{
// Create signature configuration from PFX (or P12) file
SignatureConfiguration signature = session.createSignatureFromCertificate(pfxStr, password);
// Choose first signature field
for (int i = 0; i < inDoc.getSignatureFields().size(); i++) {
if (inDoc.getSignatureFields().get(i) != null) {
signature.setFieldName(inDoc.getSignatureFields().get(i).getFieldName());
break;
}
}
try (
// Create appearance from either an XML or a JSON file
FileStream appConfigStr = new FileStream(appConfigFile, FileStream.Mode.READ_ONLY))
{
if (appConfigFile.toLowerCase().endsWith(".xml"))
signature.setAppearance(Appearance.createFromXml(appConfigStr));
else
signature.setAppearance(Appearance.createFromJson(appConfigStr));
signature.getAppearance().getCustomTextVariables().put("company", "Daily Planet");
try(
// Create a stream for the output file
FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW);
// Sign the input document
Document outDoc = new Signer().sign(inDoc, signature, outStr))
{
}
}
}
```
---
## Use a time-stamp authority
A time-stamp authority (TSA) provides trusted, cryptographically secure time-stamp information.
This time-stamp information can be used to apply a digital time-stamp to a document, which verifies that the document existed at a point in time, and that the content of the document has not been changed.
The TSA must support the time-stamp protocol as defined in the [IETF RFC 3161](https://www.ietf.org/rfc/rfc3161.txt).
The [GlobalSign](provider-globalsign.mdx) and [Swisscom](provider-swisscom.mdx) cryptographic providers have their own TSA with which the user can generate trusted time-stamp information.
The [Built-in](provider-builtin.mdx) and [PKCS#11](provider-pkcs11.mdx) cryptographic providers require a third-party TSA to be configured.
To configure the TSA, you must pass the [URI of the TSA](#time-stamp-authority-uri) to the cryptographic provider and call the `CreateTimestamp` method.
## Time-stamp authority URI
When [applying a digital time-stamp to a document](sign-timestamp.mdx), the time-stamp authority (TSA) URI must be passed to the cryptographic provider in the `TimestampUrl` property.
The `TimestampUrl` property value must be a URI with the following elements:
```
http[s]://[‹user›[:‹password›]@]‹host›[:‹port›][/‹resource›]
```
Where:
- `http/https`: Protocol for connecting to the TSA.
- `‹user›:‹password›` (optional): Credentials for connecting to the TSA (basic authorization).
- `‹host›`: Hostname of the TSA.
- `‹port›`: Port for connecting to the TSA.
- `‹resource›`: The resource.
## HTTPS connections
When connecting to the time-stamp authority using HTTPS (SSL/TLS) communication, the server certificate's trustworthiness is verified using the system's default trust store (CA certificate store). For information about configuring the trust store, see [Configure HTTPS connections](configure-digital-signing.mdx#configuring-https-connections).
## Proxy server
In a secured environment, the firewall must be configured to allow a connection to the time-stamp authority. If a [proxy server](configure-digital-signing.mdx#using-a-proxy-server) is used, the following MIME types must be supported:
- `application/timestamp-query`
- `application/timestamp-reply`
---
## A primer on PDF accessibility
import DocCardList from '@theme/DocCardList';
The primary goal of accessibility compliance is to ensure that individuals with disabilities can access and use information equally. This is achieved through measures that either directly assist the user or support the assistive technologies they use.
## Why accessibility matters for humans and machines
A truly accessible PDF serves:
- **Users**: An accessible PDF provides navigational aids like a clear structure, bookmarks, and proper reading order. The accessible PDF makes content legible through suitable contrast and colors and provides text alternatives for non-text content like images for screen readers. This helps not only users with permanent visual impairments but also those with temporary disabilities or anyone trying to read a document on a small mobile screen.
- **Machines**: A well-tagged PDF becomes a machine-readable document, enabling robust data extraction, reliable text searching, and content re-use, where you can rearrange content to fit different screen sizes without losing its meaning or structure.
## Pillars of an accessible PDF
Key components determine a PDF document’s accessibility:
- **Searchable and selectable text**: The document must contain real text, not just images of text, so screen readers can access it and users can search it.
- **Alternative text for images**: All meaningful images must have alternative text (`alt-text`) that describes their content or function.
- **Logical structure and reading order**: You must tag the document with a hierarchical structure tree that defines the reading order and identifies elements like headings, paragraphs, lists, and tables.
- **Navigational aids**: Bookmarks, a table of contents, and logical heading structures help users navigate the document efficiently.
- **Contrast and visual design**: To improve readability, text must have enough contrast against its background. However, contrast should not be the only means of conveying information.
- **Language specification**: To allow screen readers to use the correct pronunciation, specify the primary language and any language changes.
The following standards and best practices define these accessibility requirements:
- **[PDF/UA (ISO 14289)](https://www.iso.org/standard/64599.html)**: The international standard for accessible PDF documents.
- **[WCAG 2.1](https://www.w3.org/WAI/WCAG21/quickref/)**: Web Content Accessibility Guidelines applicable to PDFs.
- **[Well-Tagged PDF](https://www.adobe.com/accessibility/pdf/pdf-accessibility-overview.html)**: Best practices for document structure.
## Human in the loop
While this SDK handles the technical implementation, creating accessible PDF documents requires human understanding and judgment. Accessibility goes beyond technical compliance. Accessibility requires understanding how people actually use documents.
- **Expertise**: Understanding the standards, formats, and workflows.
- **Perspective**: Thinking from the user’s point of view.
- **Tools**: Using software that handles the technical heavy lifting.
- **Plain language**: Writing content that people with cognitive disabilities can understand.
The accessibility software provided by Pdftools ensures technical compliance, but human oversight is essential to confirm that the document is genuinely usable and understandable. This includes using clear, simple language and avoiding jargon—principles of plain language that make documents accessible to people with cognitive disabilities, learning differences, or limited literacy skills.
## Accessibility guides
Learn how to improve PDF accessibility using the Toolbox add-on SDK by following these guides:
```csharp
// Open input document
using Stream inStream = new FileStream(inPath, FileMode.Open, FileAccess.Read);
using Document inDoc = Document.Open(inStream, null);
// Create output document
using Stream outStream = new FileStream(outPath, FileMode.Create, FileAccess.ReadWrite);
using Document outDoc = Document.Create(outStream, inDoc.Conformance, null);
CopyDocumentData(inDoc, outDoc);
// Set required metadata for PDF/UA compliance
outDoc.Language = "en";
outDoc.Metadata.Title = "TaggedPDF";
outDoc.ViewerSettings.DisplayDocumentTitle = true;
// Remediating a PDF manually requires knowledge of the input PDF's layout.
// This example assumes that the input is a single-page PDF.
if (inDoc.Pages.Count != 1)
throw new InvalidOperationException("Unexpected number of pages: " + inDoc.Pages.Count);
RemediatePage(inDoc, 0, outDoc);
outDoc.SetPdfUaConformant();
```
```java
try (FileStream inStream = new FileStream(inPath, FileStream.Mode.READ_ONLY);
Document inDoc = Document.open(inStream, null);
FileStream outStream = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW);
Document outDoc = Document.create(outStream, inDoc.getConformance(), null)) {
copyDocumentData(inDoc, outDoc);
// Set required metadata for PDF/UA compliance
outDoc.setLanguage("en");
outDoc.getMetadata().setTitle("TaggedPDF");
outDoc.getViewerSettings().setDisplayDocumentTitle(true);
// Remediating a PDF manually requires knowledge of the input PDF's layout.
// This example assumes that the input is a single-page PDF.
if (inDoc.getPages().size() != 1) {
throw new IllegalStateException("Unexpected number of pages: " + inDoc.getPages().size());
}
remediatePage(inDoc, 0, outDoc);
outDoc.setPdfUaConformant();
}
```
```python
# Open input document
with open(in_path, 'rb') as in_stream:
with Document.open(in_stream, None) as in_doc:
# Create output document
with open(out_path, 'wb+') as out_stream:
with Document.create(out_stream, in_doc.conformance, None) as out_doc:
copy_document_data(in_doc, out_doc)
# Set required metadata for PDF/UA compliance
out_doc.language = "en"
out_doc.metadata.title = "TaggedPDF"
out_doc.viewer_settings.display_document_title = True
# Remediating a PDF manually requires knowledge of the input PDF's layout.
# This example assumes that the input is a single-page PDF.
if len(in_doc.pages) != 1:
raise ValueError(f"Unexpected number of pages: {len(in_doc.pages)}")
remediate_page(in_doc, 0, out_doc)
out_doc.set_pdf_ua_conformant()
```
## Creating the logical structure tree
The RemediatePage method handles the page-level remediation process. It begins by creating a new, empty page in the output document that matches the dimensions of the original page.
```csharp
private static void RemediatePage(Document inDoc, int pageIndex, Document outDoc)
{
Page inPage = inDoc.Pages[pageIndex];
Page outPage = Page.Create(outDoc, inPage.Size);
CopyAndTagContent(inPage, outPage, outDoc);
outDoc.Pages.Add(outPage);
}
```
```java
private static void remediatePage(Document inDoc, int pageIndex, Document outDoc) throws Exception {
Page inPage = inDoc.getPages().get(pageIndex);
Page outPage = Page.create(outDoc, inPage.getSize());
copyAndTagContent(inPage, outPage, outDoc);
outDoc.getPages().add(outPage);
}
```
```python
def remediate_page(in_doc: Document, page_index: int, out_doc: Document):
in_page = in_doc.pages[page_index]
out_page = Page.create(out_doc, in_page.size)
copy_and_tag_content(in_page, out_page, out_doc)
out_doc.pages.append(out_page)
```
Instantiating a `Tree` object creates the logical structure on the first call and returns the existing tree on all later calls. The root node is always of type `DocumentNode`. For this example, the code wraps the entire page in a section node (`Sect`) to define the high-level logical structure.
Next, a `ContentExtractor` retrieves content elements from the source page, and a `ContentGenerator` re-creates them on the destination page. The `for-loop` iterates through each element from the source page, identifies it, applies the correct tag, and then copies it to the destination.
```csharp
private static void CopyAndTagContent(Page inPage, Page outPage, Document outDoc)
{
// Create or retrieve the structure tree.
var structTree = new Tree(outDoc);
var documentNode = structTree.DocumentNode;
// Create a section node for the page content and add it to the document structure.
var section = new Node("Sect", outDoc, outPage);
documentNode.Children.Add(section);
ContentExtractor extractor = new ContentExtractor(inPage.Content);
using ContentGenerator generator = new ContentGenerator(outPage.Content, false);
foreach (ContentElement element in extractor)
{
// The logic to identify, tag, and add the element to the generator goes here.
// This process is detailed in the following examples
// and is specific to the document's layout.
// PDF/UA requires all content to be tagged.
// Throw an exception for any unrecognized element to avoid untagged content.
throw new InvalidOperationException("Unexpected content element found.");
}
}
```
```java
private static void copyAndTagContent(Page inPage, Page outPage, Document outDoc) throws Exception {
// Create or retrieve the structure tree.
Tree structTree = new Tree(outDoc);
Node documentNode = structTree.getDocumentNode();
// Create a section node for the page content and add it to the document structure.
Node section = new Node("Sect", outDoc, outPage);
documentNode.getChildren().add(section);
ContentExtractor extractor = new ContentExtractor(inPage.getContent());
try (ContentGenerator generator = new ContentGenerator(outPage.getContent(), false)) {
for (ContentElement element : extractor) {
// The logic to identify, tag, and add the element to the generator goes here.
// This process is detailed in the following examples
// and is specific to the document's layout.
// PDF/UA requires all content to be tagged.
// Throw an exception for any unrecognized element to avoid untagged content.
throw new IllegalStateException("Unexpected content element found.");
}
}
}
```
```python
def copy_and_tag_content(in_page: Page, out_page: Page, out_doc: Document):
# Create or retrieve the structure tree.
struct_tree = Tree(out_doc)
document_node = struct_tree.document_node
# Create a section node for the page content and add it to the document structure.
section = Node("Sect", out_doc, out_page)
document_node.children.append(section)
extractor = ContentExtractor(in_page.content)
with ContentGenerator(out_page.content, False) as generator:
for element in extractor:
# The logic to identify, tag, and add the element to the generator goes here.
# This process is detailed in the following examples
# and is specific to the document's layout.
# PDF/UA requires all content to be tagged.
# Throw an exception for any unrecognized element to avoid untagged content.
raise ValueError("Unexpected content element found.")
```
## Identifying and copying content
Identifying content elements to apply the correct tag requires specific knowledge of the document's layout. You can use specific properties for this identification. For instance, text elements have identifiable content, while non-textual elements like images have identifiable positions and sizes on the page (for example, by their bounding box).
The following code demonstrates these two approaches. This logic goes inside the for each loop shown earlier.
```csharp
if (element is TextElement textElement)
{
if (textElement.Text[0].Text == "This is a properly tagged heading")
{
CopyAndTagTextElement(textElement, section, generator, outPage, outDoc, "H1");
continue;
}
if (textElement.Text[0].Text.StartsWith("This is a properly tagged paragraph."))
{
CopyAndTagTextElement(textElement, section, generator, outPage, outDoc, "P");
continue;
}
// Add more logic here to identify other text elements.
}
else if (element is ImageElement imageElement)
{
var bbox = imageElement.Transform.TransformRectangle(element.BoundingBox);
if (Math.Abs(bbox.BottomLeft.X - 56.7) < 0.5
&& Math.Abs(bbox.BottomLeft.Y - 600.489) < 0.5
&& Math.Abs(bbox.TopRight.X - 152.489) < 0.5
&& Math.Abs(bbox.TopRight.Y - 696.489) < 0.5)
{
CopyAndTagImageElement(imageElement, documentNode, generator, outPage, outDoc, "PdfTools AG Logo");
continue;
}
// Add more logic here to identify other image elements.
}
// Remember, if an element is not identified by the logic above, the surrounding
// code will throw an exception to ensure all content is tagged.
```
```java
if (element instanceof TextElement) {
TextElement textElement = (TextElement) element;
if (textElement.getText().get(0).getText().equals("This is a properly tagged heading")) {
copyAndTagTextElement(textElement, section, generator, outPage, outDoc, "H1");
continue;
}
if (textElement.getText().get(0).getText().startsWith("This is a properly tagged paragraph.")) {
copyAndTagTextElement(textElement, section, generator, outPage, outDoc, "P");
continue;
}
// Add more logic here to identify other text elements.
} else if (element instanceof ImageElement) {
ImageElement imageElement = (ImageElement) element;
Quadrilateral bbox = imageElement.getTransform().transformRectangle(element.getBoundingBox());
if (Math.abs(bbox.getBottomLeft().getX() - 56.7) < 0.5
&& Math.abs(bbox.getBottomLeft().getY() - 600.489) < 0.5
&& Math.abs(bbox.getTopRight().getX() - 152.489) < 0.5
&& Math.abs(bbox.getTopRight().getY() - 696.489) < 0.5) {
copyAndTagImageElement(imageElement, documentNode, generator, outPage, outDoc, "PdfTools AG Logo");
continue;
}
// Add more logic here to identify other image elements.
}
// Remember, if an element is not identified by the logic above, the surrounding
// code will throw an exception to ensure all content is tagged.
```
```python
if isinstance(element, TextElement):
if element.text[0].text == "This is a properly tagged heading":
copy_and_tag_text_element(element, section, generator, out_page, out_doc, "H1")
continue
if element.text[0].text.startswith("This is a properly tagged paragraph."):
copy_and_tag_text_element(element, section, generator, out_page, out_doc, "P")
continue
# Add more logic here to identify other text elements.
elif isinstance(element, ImageElement):
bbox = element.transform.transform_rectangle(element.bounding_box)
if (abs(bbox.bottom_left.x - 56.7) < 0.5
and abs(bbox.bottom_left.y - 600.489) < 0.5
and abs(bbox.top_right.x - 152.489) < 0.5
and abs(bbox.top_right.y - 696.489) < 0.5):
copy_and_tag_image_element(element, document_node, generator, out_page, out_doc, "PdfTools AG Logo")
continue
# Add more logic here to identify other image elements.
# Remember, if an element is not identified by the logic above, the surrounding
# code will throw an exception to ensure all content is tagged.
```
## Tagging specific content elements
The key to successful remediation involves identifying which content elements need structure tags and applying the suitable tags. The following examples show how to handle different types of content:
### Tagging text elements
When tagging text, the main goal involves assigning the correct semantic role, such as a heading `H1`, a paragraph `P`, or a list item `LI`. Providing `ActualText` is also crucial for ensuring that screen readers and other assistive technologies can accurately interpret the content.
```csharp
private static void CopyAndTagTextElement(
TextElement inElement, Node section, ContentGenerator generator,
Page outPage, Document outDoc, string tag)
{
// Create a text structure node (e.g., "H1"), set its ActualText
// for accessibility, and add it to the parent section.
Node headerElement = new Node(tag, outDoc, outPage);
headerElement.ActualText = inElement.Text[0].Text;
headerElement.Language = "en";
section.Children.Add(headerElement);
// Wrap the original text element in the new tag and add it to the page content.
generator.TagAs(headerElement);
generator.AppendContentElement(ContentElement.Copy(outDoc, inElement));
generator.StopTagging();
}
```
```java
private static void copyAndTagTextElement(
TextElement inElement, Node section, ContentGenerator generator,
Page outPage, Document outDoc, String tag) throws Exception {
// Create a text structure node (e.g., "H1"), set its ActualText
// for accessibility, and add it to the parent section.
Node headerElement = new Node(tag, outDoc, outPage);
headerElement.setActualText(inElement.getText().get(0).getText());
headerElement.setLanguage("en");
section.getChildren().add(headerElement);
// Wrap the original text element in the new tag and add it to the page content.
generator.tagAs(headerElement);
generator.appendContentElement(ContentElement.copy(outDoc, inElement));
generator.stopTagging();
}
```
```python
def copy_and_tag_text_element(
in_element: TextElement, section: Node, generator: ContentGenerator,
out_page: Page, out_doc: Document, tag: str
):
# Create a text structure node (e.g., "H1"), set its ActualText
# for accessibility, and add it to the parent section.
header_element = Node(tag, out_doc, out_page)
header_element.actual_text = in_element.text[0].text
header_element.language = "en"
section.children.append(header_element)
# Wrap the original text element in the new tag and add it to the page content.
generator.tag_as(header_element)
generator.append_content_element(ContentElement.copy(out_doc, in_element))
generator.stop_tagging()
```
### Tagging image elements
For images, the most important accessibility feature involves providing descriptive alternate text. Screen readers read this text aloud for users who can't see the image. Images typically are tagged as `Figure` elements, and you need to define their bounding box to associate the tag with the correct location on the page.
```csharp
private static void CopyAndTagImageElement(
ImageElement inElement, Node documentNode, ContentGenerator generator,
Page outPage, Document outDoc, string alternateText)
{
// Create a "Figure" structure node, set its accessibility properties
// (Alternate Text, Bounding Box), and add it to the document's structure tree.
Node imgNode = new Node("Figure", outDoc, outPage);
imgNode.AlternateText = alternateText;
imgNode.Language = "en";
Quadrilateral bbox = inElement.Transform.TransformRectangle(inElement.BoundingBox);
Rectangle rectangle = new Rectangle();
rectangle.Left = bbox.BottomLeft.X;
rectangle.Bottom = bbox.BottomLeft.Y;
rectangle.Right = bbox.TopRight.X;
rectangle.Top = bbox.TopRight.Y;
imgNode.BoundingBox = rectangle;
imgNode.SetStringAttribute("O", "Layout");
documentNode.Children.Add(imgNode);
// Wrap the original image element in the new tag and add it to the page content.
generator.TagAs(imgNode);
generator.AppendContentElement(ContentElement.Copy(outDoc, inElement));
generator.StopTagging();
}
```
```java
private static void copyAndTagImageElement(
ImageElement inElement, Node documentNode, ContentGenerator generator,
Page outPage, Document outDoc, String alternateText) throws Exception {
// Create a "Figure" structure node, set its accessibility properties
// (Alternate Text, Bounding Box), and add it to the document's structure tree.
Node imgNode = new Node("Figure", outDoc, outPage);
imgNode.setAlternateText(alternateText);
imgNode.setLanguage("en");
Quadrilateral bbox = inElement.getTransform().transformRectangle(inElement.getBoundingBox());
Rectangle rectangle = new Rectangle();
rectangle.setLeft(bbox.getBottomLeft().getX());
rectangle.setBottom(bbox.getBottomLeft().getY());
rectangle.setRight(bbox.getTopRight().getX());
rectangle.setTop(bbox.getTopRight().getY());
imgNode.setBoundingBox(rectangle);
imgNode.setStringAttribute("O", "Layout");
documentNode.getChildren().add(imgNode);
// Wrap the original image element in the new tag and add it to the page content.
generator.tagAs(imgNode);
generator.appendContentElement(ContentElement.copy(outDoc, inElement));
generator.stopTagging();
}
```
```python
def copy_and_tag_image_element(
in_element: ImageElement, document_node: Node, generator: ContentGenerator,
out_page: Page, out_doc: Document, alternate_text: str
):
# Create a "Figure" structure node, set its accessibility properties
# (Alternate Text, Bounding Box), and add it to the document's structure tree.
img_node = Node("Figure", out_doc, out_page)
img_node.alternate_text = alternate_text
img_node.language = "en"
bbox = in_element.transform.transform_rectangle(in_element.bounding_box)
rectangle = Rectangle(
left=bbox.bottom_left.x,
bottom=bbox.bottom_left.y,
right=bbox.top_right.x,
top=bbox.top_right.y
)
img_node.bounding_box = rectangle
img_node.set_string_attribute("O", "Layout")
document_node.children.append(img_node)
# Wrap the original image element in the new tag and add it to the page content.
generator.tag_as(img_node)
generator.append_content_element(ContentElement.copy(out_doc, in_element))
generator.stop_tagging()
```
## Best practices for remediation
When adding logical structure to existing PDF documents, consider these best practices:
- **Content analysis**: Use heuristics to identify content types, but always validate results manually. Automated detection of headings, paragraphs, and other elements has inherent limitations.
- **Quality assurance**: Always validate the remediated PDF with accessibility checkers and screen readers to make sure the logical structure works as intended.
- **Alternative text**: Meaningful alternative text for images can't be automated. Always perform a human review before claiming PDF/UA compliance.
## Full example
Download the complete remediation example:
- [Download in C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/TagPdf/Download?technology=CS)
- [Download in Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/TagPdf/Download?technology=Java)
- [Download in Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/TagPdf/Download?technology=Python)
## Next steps
After adding logical structure to your PDF:
- **Validate the structure:** Use PDF accessibility checkers to verify the logical structure.
- **Test with assistive technology:** Ensure screen readers can navigate the document correctly.
- **Review alternative text:** Manually verify that all images have meaningful descriptions.
- **Check reading order:** Confirm the logical structure follows the intended reading flow.
:::info
Remember: adding logical structure to existing PDF documents requires technical skill, but true accessibility requires human understanding and validation. Always perform manual testing to make sure the remediated document serves its intended users effectively.
:::
---
## Create an accessible PDF from scratch
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
Using the Toolbox add-on, create fully accessible, tagged PDF documents from scratch. This guide walks you through the technical steps to create a valid PDF/UA document.
A properly structured PDF is crucial not only for users with disabilities who rely on assistive technologies but also improves the experience for all users by enabling features like content reflow on mobile devices and improving machine-readability.
:::info
This functionality is part of the Toolbox add-on, a separate SDK that you can use with the same license key as the Pdftools SDK. To use and integrate this add-on, review [Getting started with the Toolbox add-on](../../getting-started/toolbox/README.mdx) and [Toolbox add-on code samples](../../code-samples/pdftools-sdk-toolbox-samples.mdx).
:::
:::tip Quick start with a code sample
Download the full sample now in **[C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/CreateTaggedPdf/Download?technology=CS)**, **[Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/CreateTaggedPdf/Download?technology=Java)**, and **[Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/CreateTaggedPdf/Download?technology=Python)**.
Interested in Go, Rust or other programming language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.
:::
For background on PDF accessibility concepts and the importance of logical structure, review **[A primer on PDF accessibility](./README.mdx)**.
The process involves creating a document, defining its logical structure, and then adding content elements that are linked to that structure. **Steps to create a tagged PDF document**:
1. [Create the document and structure tree](#1-create-the-document-and-structure-tree)
1. [Add and tag content](#2-add-and-tag-content)
1. [Setting accessibility metadata](#2-add-and-tag-content)
---
:::note Before you begin
You need to **[initialize the library](/docs/licenses/products/pdf-tools-sdk-license/#activate-the-toolbox-add-on-license)**.
:::
### 1. Create the document and structure tree
You always start with an empty output `Document`.
```csharp
// Create a PDF document
using Stream outStream = new FileStream(outPath, FileMode.Create, FileAccess.ReadWrite);
using Document outDoc = Document.Create(outStream, null, null);
// Create a font
Font font = CreateFontWithFallbacks(outDoc, ARIAL_AND_FALLBACKS);
// Create a page
Size pageSize = new Size { Width = ToPoints(21, "cm"), Height = ToPoints(29.7, "cm") }; // DIN A4
Page outPage = Page.Create(outDoc, pageSize);
// Generate the page's content
CreateAndTagContent(outDoc, outPage, imagePath, font);
outDoc.Pages.Add(outPage);
````
```java
// Create a PDF document
try (FileStream outStream = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW);
Document outDoc = Document.create(outStream, Conformance.PDF17, null)) {
// Create a font
Font font = createFontWithFallbacks(outDoc, ARIAL_AND_FALLBACKS);
// Create a page
Size pageSize = new Size(toPoints(21, "cm"), toPoints(29.7, "cm")); // DIN A4
Page outPage = Page.create(outDoc, pageSize);
// Generate the page's content
createAndTagContent(outDoc, outPage, imagePath, font);
outDoc.getPages().add(outPage);
```
```python
# Create a PDF document
with io.FileIO(output_path, "wb+") as out_stream:
with Document.create(out_stream, Conformance.PDF17, None) as out_doc:
# Create a font
font = create_font_with_fallbacks(out_doc, ARIAL_AND_FALLBACKS)
# Create a page
page_size = Size(to_points(21, "cm"), to_points(29.7, "cm")) # DIN A4
out_page = Page.create(out_doc, page_size)
# Generate the page's content
create_and_tag_content(out_doc, out_page, image_path, font)
out_doc.pages.append(out_page)
```
:::note Helper functions and constants
Helper functions like `createFontWithFallbacks` or `toPoints` and constants like `ARIAL_AND_FALLBACKS` can be viewed in the full example.
:::
The first step is to establish the logical structure tree. This is essential because content can only be tagged if a structure node already exists for it to reference.
The structure tree begins with a `Tree` object, whose root is the `DocumentNode`. All other structure elements, like sections (`Sect`) and paragraphs (`P`), become children of this root.
```csharp
private static void CreateAndTagContent(Document outputDoc, Page outPage, string imagePath, Font font)
{
using (ContentGenerator gen = new ContentGenerator(outPage.Content, false))
{
// Create an empty logical structure tree and add a section to the root node (DocumentNode)
Tree structTree = new Tree(outputDoc);
Node docNode = structTree.DocumentNode;
Node sectionNode = new Node("Sect", outputDoc, outPage);
docNode.Children.Add(sectionNode);
// Start from the top of the page with margin
double currentY = outPage.Size.Height - MARGIN;
// Create header
currentY = CreateAndTagText(
outputDoc, outPage, gen, sectionNode, font, currentY,
"H1", "This is a properly tagged heading", 24.0);
// Add padding and create paragraph
currentY -= PADDING;
currentY = CreateAndTagText(
outputDoc, outPage, gen, sectionNode, font, currentY,
"P", "This is a properly tagged paragraph. Both heading and paragraph belong to a section.", 12.0);
// Add padding and create image
currentY -= PADDING;
CreateAndTagImage(outputDoc, outPage, gen, imagePath, currentY);
}
}
````
```java
private static void createAndTagContent(Document outDoc, Page outPage, String imagePath, Font font) throws Exception {
try (ContentGenerator gen = new ContentGenerator(outPage.getContent(), false)) {
// Create an empty logical structure tree and add a section to the root node (DocumentNode)
Tree structTree = new Tree(outDoc);
Node docNode = structTree.getDocumentNode();
Node sectionNode = new Node("Sect", outDoc, outPage);
docNode.getChildren().add(sectionNode);
// Start from the top of the page with margin
double currentY = outPage.getSize().getHeight() - MARGIN;
// Create header
currentY = createAndTagText(
outDoc, outPage, gen, sectionNode, font, currentY,
"H1", "This is a properly tagged heading", 24.0);
// Add padding and create paragraph
currentY -= PADDING;
currentY = createAndTagText(
outDoc, outPage, gen, sectionNode, font, currentY,
"P", "This is a properly tagged paragraph. Both heading and paragraph belong to a section.", 12.0);
// Add padding and create image
currentY -= PADDING;
createAndTagImage(outDoc, outPage, gen, imagePath, currentY);
}
}
```
```python
def create_and_tag_content(out_doc: Document, out_page: Page, image_path: str, font: Font):
with ContentGenerator(out_page.content, False) as gen:
# Create an empty logical structure tree and add a section to the root node (DocumentNode)
struct_tree = Tree(out_doc)
doc_node = struct_tree.document_node
section_node = Node("Sect", out_doc, out_page)
doc_node.children.append(section_node)
# Start from the top of the page with margin
current_y = out_page.size.height - MARGIN
# Create header
current_y = create_and_tag_text(
out_doc, out_page, gen, section_node, font, current_y,
"H1", "This is a properly tagged heading", 24.0)
# Add padding and create paragraph
current_y -= PADDING
current_y = create_and_tag_text(
out_doc, out_page, gen, section_node, font, current_y,
"P", "This is a properly tagged paragraph. Both heading and paragraph belong to a section.", 12.0)
# Add padding and create image
current_y -= PADDING
create_and_tag_image(out_doc, out_page, gen, image_path, current_y)
```
### 2\. Add and tag content
With the structure tree in place, you can create page content and associate it with a specific structure node. This is done using a `ContentGenerator` and its `TagAs` method. The workflow is:
1. Start tagging by calling `gen.TagAs(node)`.
2. Add the content (e.g., paint text or an image).
3. Stop tagging with `gen.StopTagging()`.
#### 2\.1. Tagging text
When tagging text elements like headings or paragraphs, the `ActualText` property of the `Node` should be set. This provides an explicit text equivalent for screen readers.
```csharp
private static double CreateAndTagText(
Document outputDoc, Page outPage, ContentGenerator gen, Node sectionNode,
Font font, double topY, string tagName, string textContent, double fontSize)
{
// Create a node in the logical structure tree
// that will contain the text and add it to the section
Node textNode = new Node(tagName, outputDoc, outPage);
textNode.ActualText = textContent;
sectionNode.Children.Add(textNode);
// Calculate text baseline position
double baselineY = topY - fontSize * font.Ascent;
// From here on, all painted graphics will be contained within that node
gen.TagAs(textNode);
// Paint text onto the page
Text text = Text.Create(outputDoc);
using (TextGenerator textGen = new TextGenerator(text, font, fontSize, null))
{
Point position = new Point { X = MARGIN, Y = baselineY };
textGen.MoveTo(position);
textGen.ShowLine(textNode.ActualText);
}
gen.PaintText(text);
gen.StopTagging();
// Return bottom coordinate (baseline - descent)
return baselineY - fontSize * font.Descent;
}
```
```java
private static double createAndTagText(
Document outDoc, Page outPage, ContentGenerator gen, Node sectionNode,
Font font, double topY, String tagName, String textContent, double fontSize) throws Exception {
// Create a node in the logical structure tree
// that will contain the text and add it to the section
Node textNode = new Node(tagName, outDoc, outPage);
textNode.setActualText(textContent);
sectionNode.getChildren().add(textNode);
// Calculate text baseline position
double baselineY = topY - fontSize * font.getAscent();
// From here on, all painted graphics will be contained within that node
gen.tagAs(textNode);
// Paint text onto the page
Text text = Text.create(outDoc);
try (TextGenerator textGen = new TextGenerator(text, font, fontSize, null)) {
Point position = new Point(MARGIN, baselineY);
textGen.moveTo(position);
textGen.showLine(textNode.getActualText());
}
gen.paintText(text);
gen.stopTagging();
// Return bottom coordinate (baseline - descent)
return baselineY - fontSize * font.getDescent();
}
```
```python
def create_and_tag_text(
out_doc: Document, out_page: Page, gen: ContentGenerator, section_node: Node,
font: Font, top_y: float, tag_name: str, text_content: str, font_size: float) -> float:
# Create a node in the logical structure tree
# that will contain the text and add it to the section
text_node = Node(tag_name, out_doc, out_page)
text_node.actual_text = text_content
section_node.children.append(text_node)
# Calculate text baseline position
baseline_y = top_y - font_size * font.ascent
# From here on, all painted graphics will be contained within that node
gen.tag_as(text_node)
# Paint text onto the page
text = Text.create(out_doc)
with TextGenerator(text, font, font_size, None) as text_gen:
position = Point(MARGIN, baseline_y)
text_gen.move_to(position)
text_gen.show_line(text_node.actual_text)
gen.paint_text(text)
gen.stop_tagging()
# Return bottom coordinate (baseline - descent)
return baseline_y - font_size * font.descent
```
#### 2\.2. Tagging an image
For non-text content, providing a text alternative is critical. For images (`Figure` nodes), you must set the `AlternateText` property.
```csharp
private static double CreateAndTagImage(
Document outputDoc, Page outPage, ContentGenerator gen,
string imagePath, double topY)
{
// If a structure tree has already been created for the given document,
// the existing structure tree reference will be returned.
Tree tree = new Tree(outputDoc);
Node docNode = tree.DocumentNode;
Node figureNode = new Node("Figure", outputDoc, outPage);
figureNode.AlternateText = "PdfTools AG Logo";
docNode.Children.Add(figureNode);
// From here on, all painted graphics will be contained within that node
gen.TagAs(figureNode);
// Load an image
Image image;
using (Stream inImage = new FileStream(imagePath, FileMode.Open, FileAccess.Read))
{
image = Image.Create(outputDoc, inImage);
}
// Paint the image onto the page
double x = MARGIN;
double width = ToPoints(2.0, "cm");
double height = width * image.Size.Height / image.Size.Width; // preserve aspect ratio
Rectangle rect = new Rectangle
{
Left = x, // left
Bottom = topY - height, // bottom (Rectangle coordinates: bottom is lower than top)
Right = x + width, // right
Top = topY // top
};
gen.PaintImage(image, rect);
gen.StopTagging();
// Return bottom coordinate
return topY - height;
}
```
```java
private static double createAndTagImage(
Document outDoc, Page outPage, ContentGenerator gen,
String imagePath, double topY) throws Exception {
// If a structure tree has already been created for the given document,
// the existing structure tree reference will be used.
Tree tree = new Tree(outDoc);
Node docNode = tree.getDocumentNode();
Node figureNode = new Node("Figure", outDoc, outPage);
figureNode.setAlternateText("PdfTools AG Logo");
docNode.getChildren().add(figureNode);
// From here on, all painted graphics will be contained within that node
gen.tagAs(figureNode);
// Load an image
Image image;
try (FileStream inImage = new FileStream(imagePath, FileStream.Mode.READ_ONLY)) {
image = Image.create(outDoc, inImage);
}
// Paint the image onto the page
double x = MARGIN;
double width = toPoints(2.0, "cm");
double height = width * image.getSize().getHeight() / image.getSize().getWidth(); // preserve aspect ratio
Rectangle rect = new Rectangle(
x, // left
topY - height, // bottom (Rectangle coordinates: bottom is lower than top)
x + width, // right
topY // top
);
gen.paintImage(image, rect);
gen.stopTagging();
// Return bottom coordinate
return topY - height;
}
```
```python
def create_and_tag_image(
out_doc: Document, out_page: Page, gen: ContentGenerator,
image_path: str, top_y: float) -> float:
# If a structure tree has already been created for the given document,
# the existing structure tree reference will be used.
tree = Tree(out_doc)
doc_node = tree.document_node
figure_node = Node("Figure", out_doc, out_page)
figure_node.alternate_text = "PdfTools Logo"
doc_node.children.append(figure_node)
# From here on, all painted graphics will be contained within that node
gen.tag_as(figure_node)
# Load an image
with io.FileIO(image_path, "rb") as in_image:
image = Image.create(out_doc, in_image)
# Paint the image onto the page
x = MARGIN
width = to_points(2.0, "cm")
height = width * image.size.height / image.size.width # preserve aspect ratio
rect = Rectangle(
left=x,
bottom=top_y - height, # Rectangle coordinates: bottom is lower than top
right=x + width,
top=top_y,
)
gen.paint_image(image, rect)
gen.stop_tagging()
# Return bottom coordinate
return top_y - height
```
When writing alternative text, follow these best practices:
- Be descriptive but concise
- Convey the purpose of the image, not just its appearance
- Don't start with "Image of..." or "Picture of..."
- For complex diagrams, consider providing a longer description elsewhere
{/* TODO: Add section about artifact content for decorative images once SDK supports this feature */}
### 3\. Setting accessibility metadata
The SDK automatically sets the `Tagged` flag when you create a PDF's logical structure. However, you must explicitly set the PDF/UA flag when you're confident your document meets all accessibility requirements:
```csharp
// Set document metadata
outDoc.Metadata.Title = "Accessible Document Example";
outDoc.Metadata.Author = "Your Organization";
// Set language for the entire document
outDoc.Language = "en-US";
// Only set PDF/UA flag after ensuring full accessibility compliance
// This requires human verification beyond technical implementation
// outDoc.SetPdfUaConformant(); // Uncomment only after full review
```
```java
// Set document metadata
outDoc.getMetadata().setTitle("Accessible Document Example");
outDoc.getMetadata().setAuthor("Your Organization");
// Set language for the entire document
outDoc.setLanguage("en-US");
// Only set PDF/UA flag after ensuring full accessibility compliance
// This requires human verification beyond technical implementation
// outDoc.setPdfUaConformant(); // Uncomment only after full review
```
```python
# Set document metadata
out_doc.metadata.title = "Accessible Document Example"
out_doc.metadata.author = "Your Organization"
# Set language for the entire document
out_doc.language = "en-US"
# Only set PDF/UA flag after ensuring full accessibility compliance
# This requires human verification beyond technical implementation
# out_doc.set_pdf_ua_conformant() # Uncomment only after full review
```
:::warning PDF/UA compliance
Setting the PDF/UA flag indicates that your document fully complies with the PDF/UA standard. This goes beyond technical structure and includes:
- Proper color contrast ratios
- Meaningful reading order
- Appropriate use of headings
- Complete alternative descriptions
- Correct language specifications
Always perform human review before claiming PDF/UA compliance.
:::
## Full example
Download the full example to see all the pieces working together.
- [Download in C\#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/CreateTaggedPdf/Download?technology=CS)
- [Download in Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/CreateTaggedPdf/Download?technology=Java)
- [Download in Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/CreateTaggedPdf/Download?technology=Python)
## Next steps
After creating accessible PDFs:
- **Validate accessibility:** Use PDF accessibility checkers to verify your implementation
- **Test with assistive technology:** Try your PDFs with screen readers like NVDA or JAWS
- **Learn about remediation:** See our guide on adding structure to existing PDFs
- **Explore structure reading:** Learn how to read and analyze logical structure
:::info
Remember: Creating truly accessible PDFs requires both technical implementation and human understanding. While our SDK provides the tools, achieving genuine accessibility requires thoughtful consideration of how people will use your documents.
:::
---
## Read PDF logical structure
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
Use the Toolbox add-on to read and traverse the logical structure of a tagged PDF document. This guide covers the technical process of accessing and analyzing existing document structure.
If you need to add logical structure to an existing PDF, see our guide on **[Adding logical structure to existing PDFs](./add-logical-structure-to-existing-pdf.mdx)**.
:::info
This functionality is part of the Toolbox add-on, a separate SDK that you can use with the same license key as the Pdftools SDK. To use and integrate this add-on, review [Getting started with the Toolbox add-on](../../getting-started/toolbox/README.mdx) and [Toolbox add-on code samples](../../code-samples/pdftools-sdk-toolbox-samples.mdx).
:::
:::tip Quick start with a code sample
Download the full sample now in **[C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/TraverseDocumentStructure/Download?technology=CS)**, **[Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/TraverseDocumentStructure/Download?technology=Java)**, and **[Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/TraverseDocumentStructure/Download?technology=Python)**.
Interested in Go, Rust or other programming language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.
:::
For background on PDF accessibility concepts and the importance of logical structure, review **[A primer on PDF accessibility](./README.mdx)**.
Reading logical structure involves accessing and traversing the document's structure tree to extract information about tagged elements. **Steps to read PDF logical structure**:
1. [Opening the tagged document](#opening-the-tagged-document)
2. [Accessing the structure tree](#accessing-the-structure-tree)
3. [Traversing the tree recursively](#traversing-the-tree-recursively)
4. [Reading node properties](#reading-node-properties)
5. [Full example](#full-example)
---
:::note Before you begin
You need to **[initialize the library](/docs/licenses/products/pdf-tools-sdk-license/#activate-the-toolbox-add-on-license)**.
:::
## Opening the tagged document
Start by opening the PDF document that contains a logical structure. Only tagged PDFs include accessible structure information.
You can then check whether the PDF claims to be PDF/UA conformant using the is_pdf_ua_conformant property.
```csharp
// Open input document
using Stream inStream = new FileStream(inPath, FileMode.Open, FileAccess.Read);
using Document inDoc = Document.Open(inStream, null);
if (inDoc.IsPdfUaConformant)
{
Console.WriteLine("This PDF declares PDF/UA conformance.");
}
else
{
Console.WriteLine("This PDF does not declare PDF/UA conformance.");
}
```
```java
// Open input document
try (FileStream inStream = new FileStream(inPath, FileStream.Mode.READ_ONLY);
Document inDoc = Document.open(inStream, null)) {
if (inDoc.getIsPdfUaConformant()) {
System.out.println("This PDF declares PDF/UA conformance.");
} else {
System.out.println("This PDF does not declare PDF/UA conformance.");
}
```
```python
# Open input document
with open(input_file_path, "rb") as in_stream:
with Document.open(in_stream, None) as in_doc:
if in_doc.is_pdf_ua_conformant:
print("This PDF declares PDF/UA conformance.")
else:
print("This PDF does not declare PDF/UA conformance.")
```
:::warning PDF/UA Declaration
The `isPdfUaConformant` flag only reflects the PDF's metadata declaration.
It does **not** guarantee actual PDF/UA compliance — use a validator to verify true conformance.
:::
## Accessing the structure tree
Create a `Tree` object to access the document's logical structure. The tree provides access to the root document node and its children.
```csharp
// Create a structure tree object
var tree = new Tree(inDoc);
// Traverse all top-level structure elements
foreach (var child in tree.Children)
{
PrintNodeRecursively(child);
}
```
```java
// Create a structure tree object
Tree tree = new Tree(inDoc);
// Traverse all top-level structure elements
for (Node node : tree.getChildren()) {
printNodeRecursively(node, 0);
}
```
```python
# Create structure tree object
tree = Tree(in_doc)
# Traverse all top-level structure elements
for node in tree.children:
print_node_recursive(node, 0)
```
## Traversing the tree recursively
Implement a recursive function to traverse the entire structure tree. Each node can have child nodes, creating a hierarchical structure.
```csharp
static void PrintNodeRecursively(Node node, int level = 0)
{
// Print current node information
PrintProperty(level, "Tag", node.Tag);
PrintProperty(level, "Alternative text", node.AlternateText);
PrintProperty(level, "Actual text", node.ActualText);
PrintProperty(level, "Language", node.Language);
// Recursively traverse child nodes
foreach (var child in node.Children)
{
PrintNodeRecursively(child, level + 1);
}
}
```
```java
static void printNodeRecursively(Node node, int level) throws Exception {
// Print current node information
printProperty(level, "Tag", node.getTag());
printProperty(level, "Alternative text", node.getAlternateText());
printProperty(level, "Actual text", node.getActualText());
printProperty(level, "Language", node.getLanguage());
// Recursively traverse child nodes
for (Node child : node.getChildren()) {
printNodeRecursively(child, level + 1);
}
}
```
```python
def print_node_recursive(node: Node, level: int):
# Print current node information
print_property(level, "Tag", node.tag)
print_property(level, "Alternative text", node.alternate_text)
print_property(level, "Actual text", node.actual_text)
print_property(level, "Language", node.language)
# Recursively traverse child nodes
for child in node.children:
print_node_recursive(child, level + 1)
```
## Reading node properties
Each structure node contains various properties that provide information about the tagged element:
- **Tag**: The structure type (e.g., "H1", "P", "Figure", "Table")
- **Actual Text**: The text content for text elements
- **Alternative Text**: Alternative text for images and non-text elements
- **Language**: Language specification for the element
- **Abbreviation**: Expanded form of abbreviations
```csharp
static void PrintProperty(int level, String name, String value)
{
Console.Write($"{new string(' ', level * 2)}");
Console.WriteLine($"{name}: '{value}'");
}
```
```java
static void printProperty(int level, String name, String value) {
for (int i = 0; i < level; ++i) {
System.out.print(" ");
}
System.out.println(name + ": '" + value + "'");
}
```
```python
def print_property(level: int, label: str, value):
indent = " " * level
value_str = str(value or "")
print(f"{indent}{label}: '{value_str}'")
```
## Example output
When you run the structure traversal, the output is similar to the following:
```
This PDF declares PDF/UA conformance.
Tag: 'Document'
Alternative text: ''
Actual text: ''
Language: ''
Tag: 'Title'
Alternative text: ''
Actual text: ''
Language: ''
Tag: 'Text body'
Alternative text: ''
Actual text: ''
Language: ''
Tag: 'Text body'
Alternative text: ''
Actual text: ''
Language: ''
Tag: 'Figure'
Alternative text: 'A test image of a document icon'
Actual text: ''
Language: ''
```
## Full example
Download the complete structure traversal example:
- [Download in C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/TraverseDocumentStructure/Download?technology=CS)
- [Download in Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/TraverseDocumentStructure/Download?technology=Java)
- [Download in Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/TraverseDocumentStructure/Download?technology=Python)
## Use cases
Reading logical structure is useful for:
- **Accessibility auditing**: Verify that documents have proper structure
- **Content extraction**: Extract structured content while preserving hierarchy
- **Document analysis**: Understand document organization and reading order
- **Quality assurance**: Validate that remediation or creation processes worked correctly
Reading logical structure provides insights into how assistive technologies will interpret your PDF documents, making it an essential tool for accessibility validation.
---
## Add and fill form fields(Toolbox)
The Toolbox add-on lets you add and fill form fields in PDF documents.
:::info
This functionality is part of the Toolbox add-on, a separate SDK that you can use with the same license key as the Pdftools SDK. To use and integrate this add-on, review [Getting started with the Toolbox add-on](../../getting-started/toolbox/) and [Toolbox add-on code samples](../code-samples/pdftools-sdk-toolbox-samples.mdx).
:::
## Form fields
Form fields are placeholders for input data in a PDF document. An example of such input data might be a name, a date, or a choice from a group of items. The input data contained in a form field may be modified, if allowed, by the user who is viewing the PDF document.
The Toolbox add-on supports the following types of form fields:
- `General text`
- `Comb text`
- `Check box`
- `Radio button`
- `Combo box`
- `List box`
The special type `SubForm` can also be used to create logical groups of form fields.
## Add form fields
Learn how to add form fields to a PDF document using the [Add Form Field](../../code-samples/pdftools-sdk-toolbox-samples/#add-form-field) sample project.
:::tip Quick start with a code sample
Download the full sample now in **[C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/AddFormFields/Download?technology=CS)**, **[Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/AddFormFields/Download?technology=Java)**, and **[Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/AddFormFields/Download?technology=Python)**.
Interested in C, Go, Rust or other programming language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.
:::
## Fill form fields
You can learn how to fill form fields in a PDF document using out [Fill Form Fields](../../code-samples/pdftools-sdk-toolbox-samples/#fill-form-fields) sample project.
:::tip Quick start with a code sample
Download the full sample now in **[C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/FillFormFields/Download?technology=C)**, **[C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/FillFormFields/Download?technology=CS)**, **[Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/FillFormFields/Download?technology=Java)**, and **[Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/FillFormFields/Download?technology=Python)**.
Interested in C, Go, Rust or other programming language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.
:::
{/*
Ben's Note: I don't want to lose all the content below, but it's too technical and there is too much compared to all the other Toolbox functional areas right now. So I will comment it out until we have a chance to go through and edit it, and also add content for all the other areas.
Form fields are structured in a tree topology in which the `Document` acts as the tree root. The immediate child form field nodes thereof can be accessed via the `Document.FormFields` property.
Each child form field node in the tree can itself have more children. Such form field is called a “sub form”. A child form field node that has no children is simply a “form field”.
There are several form field subtypes:
In the PDF Toolbox SDK, the subtypes are modeled by classes that inherit from a base class `FieldNode` in the following way:
`FieldNodes` are contained in a `FieldNodeMap` in the form of key-value pairs, for which the keys act as form field node identifiers. The identifier must not contain any full stops (“.”).
The fully qualified identifier of a form field node is defined as the concatenation of all its ancestor `SubForm`’s identifiers and its own identifier, separated by full stops (“.”), e.g. `MySubForm.MyField`. The fully qualified identifier of each form field node is unique within a document.
While the form field tree models the form’s data, the visual manifestations of form fields are managed by Widgets contained in `Page.Widgets`, of which each form field has at least one.
## Add form fields
In an output document (a document created with `Document.Create`), form fields can be created from scratch by means of the following methods:
- `CheckBox.Create`
- `ComboBox.Create`
- `CombTextField.Create`
- `GeneralTextField.Create`
- `ListBox.Create`
- `RadioButtonGroup.Create`
- `SubForm.Create`
A `PushButton` cannot be created.
After creating a `ChoiceField`, i.e. a `ComboBox` or a `ListBox`, `ChoiceItems` should be created and added with the `ChoiceField.AddNewItem` method.
After creating a `RadioButtonGroup`, new `RadioButtons` should be created and added with the `RadioButtonGroup.AddNewButton` method.
Each created form field must be added either to the document’s `Document.FormFields`, or to the `SubForm.Children` of a `SubForm`.
You should set all form field properties prior to creating any Widgets. Specifically, changing form field properties that affect the form field’s visual appearance fails with an `UnsupportedOperation` error if the form field has widgets.
For each form field, at least one Widget should be created using the `RadioButton.AddNewWidget` method for radio button groups, or the form field’s `Field.AddNewWidget` method for all other field types.
Finally, each created widget must be added to one of the Page.Widgets of any of the document’s `Pages`.
A page can either be created from scratch with the `Page.Create` method or it can be copied with `Page.Copy` from an input document (a document created with `Document.Open`). In the latter case, `PageCopyOptions.FormFields` must not be set to `FormFieldCopyStrategy.Copy` and `PageCopyOptions.UnsignedSignatures` not to `CopyStrategy.Copy`.
The combination of creating form fields and copying form fields or unsigned signatures via `Page.Copy` or `PageList.Copy` (with `PageCopyOption` argument in which either the `PageCopyOptions.FormFields` property is set to `FormFieldCopyStrategy.Copy` or the `PageCopyOptions.UnsignedSignatures` property is set to `CopyStrategy.Copy`) is not supported. Specifically:
- Once `Page.Copy` or `PageList.Copy` has been called with `PageCopyOptions.FormFields` set to `FormFieldCopyStrategy.Copy` or `PageCopyOptions.UnsignedSignatures` set to `CopyStrategy.Copy`, any subsequent call to any of the form field creation methods fails with an `IllegalState` error.
- Once any of the form field creation methods has been called, any subsequent call to `Page.Copy` or `PageList.Copy` with `PageCopyOptions.FormFields` set to `FormFieldCopyStrategy.Copy` or `PageCopyOptions.UnsignedSignatures` set to `CopyStrategy.Copy` fails with an `IllegalArgument` error.
## Fill form fields
Filling a form means that the values (field content) of form fields are modified. Depending on the field type, this implies the following:
- `TextField`: modify text using `TextField.Text`.
- `CheckBox`: modify the state using `CheckBox.Checked`.
- `RadioButtonGroup`: modify the choice using `RadioButtonGroup.ChosenButton`.
- `ComboBox`: modify choice using `ComboBox.ChosenItem` or `ComboBox.EditableItemName`.
- `ListBox`: modify choice using `ListBox.ChosenItems`.
To use the PDF Toolbox SDK for filling out the values of form fields in a PDF, the following procedure must be followed:
1. An input document is opened with `Document.Open` and an output document is created with `Document.Create`.
2. Before copying pages, the form fields must be copied from the input document to the output document as
follows:
1. Access the form field node map of the input and the output document via `Document.FormFields`.
2. Copy each form field node found in the input to the output document using the FieldNode.Copy method.
Copying `SubForms` automatically copies their children. (Note that the copied form fields have no widgets yet.)
3. The value of a copied form field can be modified here or later in Step 3.
4. Add each copied form field node to the output document’s field node `mapDocument.FormFields`, preferably using the same key as used in the input document’s field node map
3. The output document’s form field nodes can be accessed, e.g. using FieldNodeMap.Lookup to modify form
field values.
4. Copy all pages with the `PageList.Copy` method. Hereby, the `PageCopyOptions.FormFields` property in the `PageCopyOptions` argument must be set to `FormFieldCopyStrategy.CopyAndUpdateWidgets` and the `PageCopyOptions.UnsignedSignatures` must be set to `CopyStrategy.Remove` or `CopyStrategy.Flatten`. In this step, the Widgets of input form fields are copied to the output form fields and automatically updated to reflect the new form field values. (As soon as a form field has Widgets, its value can no longer be modified.)
The combination of filling form fields and copying form fields via `Page.Copy` or `PageList.Copy` (with `PageCopyOptions` argument in which `CopyOptions.FormFields` is set to `FormFieldCopyStrategy.Copy`) is
not supported. Specifically:
- Once `Page.Copy` or `PageList.Copy` has been called with `PageCopyOptions.FormFields` set to `FormFieldCopyStrategy.Copy`, any subsequent call to `FieldNode.Copy` fails with an IllegalState error.
- When `FieldNode.Copy` was called, any subsequent call to `Page.Copy` or `PageList.Copy` with `PageCopyOptions.FormFields` set to `FormFieldCopyStrategy.Copy` or `PageCopyOptions.UnsignedSignatures` set to `CopyStrategy.Copy` fails with an `IllegalArgument` error.
*/}
---
## Manage annotations(Toolbox)
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
Manage annotations in PDF files with the Toolbox add-on.
PDF annotations let you add comments, suggestions, and markup-like shapes and highlights to PDFs. Annotations are not part of the page content as they are applied on the top of a page. In contrast to ordinary page content, many annotation types behave interactively in PDF viewers.
:::info
This functionality is part of the Toolbox add-on, a separate SDK that you can use with the same license key as the Pdftools SDK. To use and integrate this add-on, review [Getting started with the Toolbox add-on](../../getting-started/toolbox/) and [Toolbox add-on code samples](../code-samples/pdftools-sdk-toolbox-samples.mdx).
:::
:::tip Quick start with a code sample
Download the full sample now in **[C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/AddAnnotations/Download?technology=CS)**, **[Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/AddAnnotations/Download?technology=Java)**, and **[Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/AddAnnotations/Download?technology=Python)**.
Interested in C, Go, Rust or other programming language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.
:::
The Toolbox add-on supports the following types of annotations:
| Type | Annotation name |
| --------------- | ---------------------- |
| Text Markup | `Highlight``Popup``StickyNote``StrikeThrough``Underline``FreeText` |
| Shape | `Ellipse``Ink``Line``Polygon``PolyLine``Rectangle``Squiggly` |
| Navigation | `InternalLink``WebLink` |
| Stamp | `TextStamp``CustomStamp` |
| File | `FileAttachment` |
**Steps to add annotations to a document**:
1. [Reading the input document](#reading-the-input-document)
2. [Copying document-wide data](#copying-document-wide-data)
3. [Copying and annotating the input pages](#copying-and-annotating-the-input-pages)
4. [Adding copied pages to the output document](#adding-copied-pages-to-the-output-document)
5. [Full example](#full-example)
:::note Before you begin
You need to **[initialize the library](/docs/licenses/products/pdf-tools-sdk-license/#activate-the-toolbox-add-on-license)**.
:::
## Reading the input document
Read the PDF file you want to annotate by loading the input document from the file system into a read-only input `Document` object.
At the same time, create a writeable output `Document` object that contains the annotated output PDF file.
```csharp
// Open input document
using (Stream inStream = new FileStream(inPath, FileMode.Open, FileAccess.Read))
using (Document inDoc = Document.Open(inStream, null))
{
// Create output document
using Stream outStream = new FileStream(outPath, FileMode.Create, FileAccess.ReadWrite);
using Document outDoc = Document.Create(outStream, inDoc.Conformance, null);
```
```java
try (// Open input document
FileStream inStream = new FileStream(inPath, FileStream.Mode.READ_ONLY);
Document inDoc = Document.open(inStream, null);
// Create file stream
FileStream outStream = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW)) {
try (// Create output document
Document outDoc = Document.create(outStream, inDoc.getConformance(), null)) {
```
## Copying document-wide data
In the Toolbox add-on, you always start with an empty output document (unlike the Pdftools SDK). To retain document-wide information you must explicitly copy it from the input document to the output. Document-wide information includes:
- Metadata
- Viewer settings
- Embedded files
You can control which document-wide information is kept and which is removed using the `CopyDocumentData` function. In this example, all document-wide information is copied from the input document to the output document.
```csharp
// Copy document-wide data
CopyDocumentData(inDoc, outDoc);
```
```java
// Copy document-wide data
copyDocumentData(inDoc, outDoc);
```
CopyDocumentData function
```csharp
private static void CopyDocumentData(Document inDoc, Document outDoc)
{
// Copy document-wide data
// Output intent
if (inDoc.OutputIntent != null)
outDoc.OutputIntent = IccBasedColorSpace.Copy(outDoc, inDoc.OutputIntent);
// Metadata
outDoc.Metadata = Metadata.Copy(outDoc, inDoc.Metadata);
// Viewer settings
outDoc.ViewerSettings = ViewerSettings.Copy(outDoc, inDoc.ViewerSettings);
// Associated files (for PDF/A-3 and PDF 2.0 only)
FileReferenceList outAssociatedFiles = outDoc.AssociatedFiles;
foreach (FileReference inFileRef in inDoc.AssociatedFiles)
outAssociatedFiles.Add(FileReference.Copy(outDoc, inFileRef));
// Plain embedded files
FileReferenceList outEmbeddedFiles = outDoc.PlainEmbeddedFiles;
foreach (FileReference inFileRef in inDoc.PlainEmbeddedFiles)
outEmbeddedFiles.Add(FileReference.Copy(outDoc, inFileRef));
}
```
```java
private static void copyDocumentData(Document inDoc, Document outDoc) throws ToolboxException, IOException {
// Copy document-wide data
// Output intent
if (inDoc.getOutputIntent() != null)
outDoc.setOutputIntent(IccBasedColorSpace.copy(outDoc, inDoc.getOutputIntent()));
// Metadata
outDoc.setMetadata(Metadata.copy(outDoc, inDoc.getMetadata()));
// Viewer settings
outDoc.setViewerSettings(ViewerSettings.copy(outDoc, inDoc.getViewerSettings()));
// Associated files (for PDF/A-3 and PDF 2.0 only)
FileReferenceList outAssociatedFiles = outDoc.getAssociatedFiles();
for (FileReference inFileRef : inDoc.getAssociatedFiles())
outAssociatedFiles.add(FileReference.copy(outDoc, inFileRef));
// Plain embedded files
FileReferenceList outEmbeddedFiles = outDoc.getPlainEmbeddedFiles();
for (FileReference inFileRef : inDoc.getPlainEmbeddedFiles())
outEmbeddedFiles.add(FileReference.copy(outDoc, inFileRef));
}
```
## Copying and annotating the input pages
When copying page content between documents, the [PageCopyOptions](https://api-reference.pdf-tools.com/pdfsdkxt/latest/dotnet/html/T_PdfTools_Toolbox_Pdf_PageCopyOptions.htm) class lets you define which types of page information to copy. For example, you can choose to copy or remove information such as annotations, form fields, and structure elements to the output page. In this example, all page information except digital signatures is copied to the output document.
The `CopyAndAddAnnotations` function copies the page content and selected page information from the first page of the input document. It then adds a `StickyNote`, an `Ellipse`, a `Highlight`, a `FreeText`, and a `WebLink` annotation to the page.
```csharp
// Define page copy options
PageCopyOptions copyOptions = new PageCopyOptions();
// Copy first page and add annotations
Page outPage = CopyAndAddAnnotations(outDoc, inDoc.Pages[0], copyOptions);
```
```java
// Define page copy options
PageCopyOptions copyOptions = new PageCopyOptions();
// Copy first page and add annotations
Page outPage = copyAndAddAnnotations(outDoc, inDoc.getPages().get(0), copyOptions);
```
CopyAndAddAnnotations function
```csharp
private static Page CopyAndAddAnnotations(Document outDoc, Page inPage, PageCopyOptions copyOptions)
{
// Copy page to output document
Page outPage = Page.Copy(outDoc, inPage, copyOptions);
// Make a RGB color space
ColorSpace rgb = ColorSpace.CreateProcessColorSpace(outDoc, ProcessColorSpaceType.Rgb);
// Get the page size for positioning annotations
Size pageSize = outPage.Size;
// Get the output page's list of annotations for adding annotations
AnnotationList annotations = outPage.Annotations;
// Create a sticky note and add to output page's annotations
Paint green = Paint.Create(outDoc, rgb, new double[] { 0, 1, 0 }, null);
Point stickyNoteTopLeft = new Point() { X = 10, Y = pageSize.Height - 10 };
StickyNote stickyNote = StickyNote.Create(outDoc, stickyNoteTopLeft, "Hello world!", green);
annotations.Add(stickyNote);
// Create an ellipse and add to output page's annotations
Paint blue = Paint.Create(outDoc, rgb, new double[] { 0, 0, 1 }, null);
Paint yellow = Paint.Create(outDoc, rgb, new double[] { 1, 1, 0 }, null);
Rectangle ellipseBox = new Rectangle() { Left = 10, Bottom = pageSize.Height - 60, Right = 70, Top = pageSize.Height - 20 };
EllipseAnnotation ellipse = EllipseAnnotation.Create(outDoc, ellipseBox, new Stroke(blue, 1.5), yellow);
annotations.Add(ellipse);
// Create a free text and add to output page's annotations
Paint yellowTransp = Paint.Create(outDoc, rgb, new double[] { 1, 1, 0 }, new Transparency(0.5));
Rectangle freeTextBox = new Rectangle() { Left = 10, Bottom = pageSize.Height - 170, Right = 120, Top = pageSize.Height - 70 };
FreeText freeText = FreeText.Create(outDoc, freeTextBox, "Lorem ipsum dolor sit amet, consectetur adipiscing elit.", yellowTransp);
annotations.Add(freeText);
// A highlight and a web-link to be fitted on existing page content elements
Highlight highlight = null;
WebLink webLink = null;
// Extract content elements from the input page
ContentExtractor extractor = new ContentExtractor(inPage.Content);
foreach (ContentElement element in extractor)
{
// Take the first text element
if (highlight == null && element is TextElement textElement)
{
// Get the quadrilaterals of this text element
QuadrilateralList quadrilaterals = new QuadrilateralList();
foreach (TextFragment fragment in textElement.Text)
quadrilaterals.Add(fragment.Transform.TransformRectangle(fragment.BoundingBox));
// Create a highlight and add to output page's annotations
highlight = Highlight.CreateFromQuadrilaterals(outDoc, quadrilaterals, yellow);
annotations.Add(highlight);
}
// Take the first image element
if (webLink == null && element is ImageElement)
{
// Get the quadrilateral of this image
QuadrilateralList quadrilaterals = new QuadrilateralList();
quadrilaterals.Add(element.Transform.TransformRectangle(element.BoundingBox));
// Create a web-link and add to the output page's links
webLink = WebLink.CreateFromQuadrilaterals(outDoc, quadrilaterals, "https://www.pdf-tools.com");
Paint red = Paint.Create(outDoc, rgb, new double[] { 1, 0, 0 }, null);
webLink.BorderStyle = new Stroke(red, 1.5);
outPage.Links.Add(webLink);
}
// Exit loop if highlight and webLink have been created
if (highlight != null && webLink != null)
break;
}
// return the finished page
return outPage;
}
```
```java
private static Page copyAndAddAnnotations(Document outDoc, Page inPage, PageCopyOptions copyOptions) throws ConformanceException, CorruptException, IOException, UnsupportedFeatureException {
// Copy page to output document
Page outPage = Page.copy(outDoc, inPage, copyOptions);
// Make a RGB color space
ColorSpace rgb = ColorSpace.createProcessColorSpace(outDoc, ProcessColorSpaceType.RGB);
// Get the page size for positioning annotations
Size pageSize = outPage.getSize();
// Get the output page's list of annotations for adding annotations
AnnotationList annotations = outPage.getAnnotations();
// Create a sticky note and add to output page's annotations
Paint green = Paint.create(outDoc, rgb, new double[] { 0, 1, 0 }, null);
Point stickyNoteTopLeft = new Point(10, pageSize.height - 10 );
StickyNote stickyNote = StickyNote.create(outDoc, stickyNoteTopLeft, "Hello world!", green);
annotations.add(stickyNote);
// Create an ellipse and add to output page's annotations
Paint blue = Paint.create(outDoc, rgb, new double[] { 0, 0, 1 }, null);
Paint yellow = Paint.create(outDoc, rgb, new double[] { 1, 1, 0 }, null);
Rectangle ellipseBox = new Rectangle(10, pageSize.height - 60, 70, pageSize.height - 20);
EllipseAnnotation ellipse = EllipseAnnotation.create(outDoc, ellipseBox, new Stroke(blue, 1.5), yellow);
annotations.add(ellipse);
// Create a free text and add to output page's annotations
Paint yellowTransp = Paint.create(outDoc, rgb, new double[] { 1, 1, 0 }, new Transparency(0.5));
Rectangle freeTextBox = new Rectangle(10, pageSize.height - 170, 120, pageSize.height - 70);
FreeText freeText = FreeText.create(outDoc, freeTextBox, "Lorem ipsum dolor sit amet, consectetur adipiscing elit.", yellowTransp);
annotations.add(freeText);
// A highlight and a web-link to be fitted on existing page content elements
Highlight highlight = null;
WebLink webLink = null;
// Extract content elements from the input page
ContentExtractor extractor = new ContentExtractor(inPage.getContent());
for (ContentElement element : extractor) {
// Take the first text element
if (highlight == null && element instanceof TextElement) {
TextElement textElement = (TextElement)element;
// Get the quadrilaterals of this text element
QuadrilateralList quadrilaterals = new QuadrilateralList();
for (TextFragment fragment : textElement.getText())
quadrilaterals.add(fragment.getTransform().transformRectangle(fragment.getBoundingBox()));
// Create a highlight and add to output page's annotations
highlight = Highlight.createFromQuadrilaterals(outDoc, quadrilaterals, yellow);
annotations.add(highlight);
}
// Take the first image element
if (webLink == null && element instanceof ImageElement) {
// Get the quadrilateral of this image
QuadrilateralList quadrilaterals = new QuadrilateralList();
quadrilaterals.add(element.getTransform().transformRectangle(element.getBoundingBox()));
// Create a web-link and add to the output page's links
webLink = WebLink.createFromQuadrilaterals(outDoc, quadrilaterals, "https://www.pdf-tools.com");
Paint red = Paint.create(outDoc, rgb, new double[] { 1, 0, 0 }, null);
webLink.setBorderStyle(new Stroke(red, 1.5));
outPage.getLinks().add(webLink);
}
// Exit loop if highlight and webLink have been created
if (highlight != null && webLink != null)
break;
}
// return the finished page
return outPage;
}
```
## Adding copied pages to the output document
After copying and adding annotations to the page, the annotated page is added to the output document. After this step, it is no longer possible to change the page.
Finally, the remaining pages are copied and added to the output document as a [PageList](https://api-reference.pdf-tools.com/pdfsdkxt/latest/dotnet/html/Methods_T_PdfTools_Toolbox_Pdf_PageList.htm).
```csharp
// Add the page to the output document's page list
outDoc.Pages.Add(outPage);
// Copy the remaining pages and add to the output document's page list
PageList inPages = inDoc.Pages.GetRange(1, inDoc.Pages.Count - 1);
PageList outPages = PageList.Copy(outDoc, inPages, copyOptions);
outDoc.Pages.AddRange(outPages);
```
```java
// Add the page to the output document's page list
outDoc.getPages().add(outPage);
// Copy the remaining pages and add to the output document's page list
PageList inPages = inDoc.getPages().subList(1, inDoc.getPages().size());
PageList outPages = PageList.copy(outDoc, inPages, copyOptions);
outDoc.getPages().addAll(outPages);
```
{/*
Add samples for loading and saving FDF files containing annotations.
*/}
## Full example
Download the full example in **[C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/AddAnnotations/Download?technology=CS)**, **[Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/AddAnnotations/Download?technology=Java)**, and **[Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/AddAnnotations/Download?technology=Python)**.
---
## Add and remove content
The Toolbox add-on lets you add content to a PDF such as text, watermarks, barcodes, and images.
:::info
This functionality is part of the Toolbox add-on, a separate SDK that you can use with the same license key as the Pdftools SDK. To use and integrate this add-on, review [Getting started with the Toolbox add-on](../../getting-started/toolbox/) and [Toolbox add-on code samples](../code-samples/pdftools-sdk-toolbox-samples.mdx).
:::
:::tip Quick start with a code sample - Add text to a PDF
Download the full sample now in **[C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/AddText/Download?technology=C)**, **[C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/AddText/Download?technology=CS)**, **[Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/AddText/Download?technology=Java)**, and **[Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/AddText/Download?technology=Python)**.
Interested in Go, Rust or other programming language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.
:::
## Content types
The Toolbox add-on supports adding the following types of content:
- `Text`
- `Image`
- `Image Mask`
- `Path`
## Add and remove content
There is a wide range of use cases for the following content types:
| Content type | Use case example |
| --------------- | ---------------------- |
| Text | [Add text to a PDF](../code-samples/pdftools-sdk-toolbox-samples.mdx#add-text-to-pdf)[Add a barcode to a PDF](../code-samples/pdftools-sdk-toolbox-samples.mdx#add-barcode-to-pdf)[Add line numbers to a PDF](../code-samples/pdftools-sdk-toolbox-samples.mdx#add-line-numbers-to-pdf)[Add a stamp to a PDF](../code-samples/pdftools-sdk-toolbox-samples.mdx#add-stamp-to-pdf)[Add page numbers to a PDF](../code-samples/pdftools-sdk-toolbox-samples.mdx#stamp-page-number-to-pdf) [Layout text in a PDF page](../code-samples/pdftools-sdk-toolbox-samples.mdx#layout-text-on-pdf-page) [Remove glyphs from a PDF](../code-samples/pdftools-sdk-toolbox-samples.mdx#remove-glyphs) [Remove white text from a PDF](../code-samples/pdftools-sdk-toolbox-samples.mdx#remove-white-text-from-pdf) |
| Image | [Add a QR code (Data Matrix) to a PDF](../code-samples/pdftools-sdk-toolbox-samples.mdx#add-data-matrix-to-pdf)[Add an image to a PDF](../code-samples/pdftools-sdk-toolbox-samples.mdx#add-image-to-pdf) |
| Image Mask | [Add an image mask to a PDF](../code-samples/pdftools-sdk-toolbox-samples.mdx#add-image-mask-to-pdf) |
| Path | [Add a vector graphic to a PDF](../code-samples/pdftools-sdk-toolbox-samples.mdx#add-vector-graphic-to-pdf) |
---
## Extract(Toolbox)
The Toolbox add-on lets you extract information such as text, images, and signatures from a PDF document. You can also extract document attributes like the conformance level, whether the document is encrypted or protected, and metadata like author, title, and creation date.
:::info
This functionality is part of the Toolbox add-on, a separate SDK that you can use with the same license key as the Pdftools SDK. To use and integrate this add-on, review [Getting started with the Toolbox add-on](../../getting-started/toolbox/) and [Toolbox add-on code samples](../code-samples/pdftools-sdk-toolbox-samples.mdx).
:::
:::tip Quick start with a code sample
Download the full sample now in **[C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/TextExtraction/Download?technology=CS)**, **[Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/TextExtraction/Download?technology=Java)**, and **[Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/TextExtraction/Download?technology=Python)**.
Interested in C, Go, Rust or other programming language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.
:::
## Extract text
Learn how to extract text content from a PDF document using the [Extract all text from PDF](../code-samples/pdftools-sdk-toolbox-samples.mdx#extract-all-text-from-pdf) sample project. This project also illustrates the use of heuristics to assemble text content into words and sentences based on their position on the page.
## Extract images
Learn how to extract images from a PDF document using the [Extract all images and image masks from a PDF](../code-samples/pdftools-sdk-toolbox-samples.mdx#extract-all-images-and-image-masks-from-a-pdf) sample project. The extract images functionality accepts an image embedded as a content element in a PDF file and outputs it as an image file.
:::note Output formats
- BMP
- JPEG
- JPEG2000
- JBIG2
- PNG
- GIF
- TIFF
:::
:::tip Quick start with a code sample
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ImageExtraction/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ImageExtraction/Download?technology=Java), and [C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ImageExtraction/Download?technology=C).
:::
## Extract signatures
Learn how to extract signature content from a PDF document using the [List Signatures in PDF](../code-samples/pdftools-sdk-toolbox-samples.mdx#list-signatures-in-pdf) sample project. You can automatically extract signature information such as name, date, and contact information.
For a guide to comprehensive validation of digital signatures, review the [Validate signatures in a signed PDF document](../sign-and-secure/sign/sign-validate.mdx) page.
:::tip Quick start with a code sample
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ListSignatures/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ListSignatures/Download?technology=Java), and [C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ListSignatures/Download?technology=C).
:::
## Extract document attributes and metadata
You can learn how to extract document attributes and metadata from a PDF document using our [List document information of PDF](../code-samples/pdftools-sdk-toolbox-samples.mdx#list-document-information-of-pdf) sample project.
:::tip Quick start with a code sample
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ListInfo/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ListInfo/Download?technology=Java), and [C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ListInfo/Download?technology=C).
:::
---
## Generate PDFs(Toolbox)
The Toolbox add-on lets you create a new PDF files from scratch using Java, .Net, and C.
After creating the PDF files, use the Toolbox add-on to [add content](./edit.mdx), [add form fields](./add-and-fill-form-fields.mdx), [manage metadata](./manage-metadata.mdx), and more.
:::info
This functionality is part of the Toolbox add-on, a separate SDK that you can use with the same license key as the Pdftools SDK. To use and integrate this add-on, review [Getting started with the Toolbox add-on](../../getting-started/toolbox/) and [Toolbox add-on code samples](../code-samples/pdftools-sdk-toolbox-samples.mdx).
:::
:::tip Quick start with a code sample
Download the full sample now in **[C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/LayoutText/Download?technology=CS)**, **[Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/LayoutText/Download?technology=Java)**, and **[Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/LayoutText/Download?technology=Python)**.
Interested in C, Go, Rust or other programming language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.
:::
## Create a new PDF document
Learn how to create a new PDF file using [Layout text on PDF page](../code-samples/pdftools-sdk-toolbox-samples.mdx#layout-text-on-pdf-page) code sample.
---
## Manage metadata(Toolbox)
The Toolbox add-on lets you add, remove, and update metadata in a PDF document. Manage standard metadata fields such as the Author, Title, and Subject. You can also manage custom metadata fields and directly update the XMP metadata with your XML content.
:::info
This functionality is part of the Toolbox add-on, a separate SDK that you can use with the same license key as the Pdftools SDK. To use and integrate this add-on, review [Getting started with the Toolbox add-on](../../getting-started/toolbox/) and [Toolbox add-on code samples](../code-samples/pdftools-sdk-toolbox-samples.mdx).
:::
:::tip Quick start with a code sample
Download the full sample now in **[C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/AddMetadata/Download?technology=C)**, **[C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/AddMetadata/Download?technology=CS)**, **[Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/AddMetadata/Download?technology=Java)**, and **[Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/AddMetadata/Download?technology=Python)**.
:::
## List document metadata
Learn how to list document attributes and metadata from a PDF document using the [List document information of PDF](../code-samples/pdftools-sdk-toolbox-samples.mdx#list-document-information-of-pdf) sample project.
:::tip Quick start with a code sample
Download the full sample now in **[C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ListInfo/Download?technology=C)**, **[C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ListInfo/Download?technology=CS)**, **[Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ListInfo/Download?technology=Java)**, and **[Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ListInfo/Download?technology=Python)**.
:::
## Add metadata
Learn how to set metadata such as the author, title, and creator of a PDF document using the [Add metadata to PDF](../code-samples/pdftools-sdk-toolbox-samples.mdx#add-metadata-to-pdf) sample project. Optionally, copy metadata from another PDF document or the content of an XMP metadata file.
---
## Layout for printing
The Toolbox add-on lets you create a layout of a PDF document that is ready for printing. Flatten form fields, set page dimensions, set page orientation, and place multiple pages onto one page.
:::info
This functionality is part of the Toolbox add-on, a separate SDK that you can use with the same license key as the Pdftools SDK. To use and integrate this add-on, review [Getting started with the Toolbox add-on](../../getting-started/toolbox/) and [Toolbox add-on code samples](../code-samples/pdftools-sdk-toolbox-samples.mdx).
:::
## Flatten form fields
You can learn how to flatten form fields in a PDF document using our [Flatten form fields](../code-samples/pdftools-sdk-toolbox-samples.mdx#flatten-form-fields-in-pdf) sample project. This process turns the form field into non-interactive content while retaining its visual appearance.
:::tip Quick start with a code sample
Download the full sample now in **[C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/FlattenFormFields/Download?technology=C)[C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/FlattenFormFields/Download?technology=CS)**, **[Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/FlattenFormFields/Download?technology=Java)**, and **[Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/FlattenFormFields/Download?technology=Python)**.
Interested in Go, Rust or other programming language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.
:::
## Set page dimensions
Learn how to set the dimensions of a PDF page using the **[Fit pages to specific page format](../code-samples/pdftools-sdk-toolbox-samples.mdx#fit-pages-to-specific-page-format) sample project. In this project, you also learn how to detect the page orientation and automatically rotate and scale it if it doesn't fit the target page format.
:::tip Quick start with a code sample
Download the full sample now in **[C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/FitPage/Download?technology=C)**, **[C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/FitPage/Download?technology=CS)**, **[Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/FitPage/Download?technology=Java)**, and **[Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/FitPage/Download?technology=Python)**.
Interested in Go, Rust or other programming language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.
:::
## Set page orientation
Learn how to adjust the orientation of a PDF page using the **[Set page orientation](../code-samples/pdftools-sdk-toolbox-samples.mdx#set-page-orientation) sample project.
:::tip Quick start with a code sample
Download the full sample now in **[C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/RotatePages/Download?technology=C)**, **[C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/RotatePages/Download?technology=CS)**, **[Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/RotatePages/Download?technology=Java)**, and **[Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/RotatePages/Download?technology=Python)**.
:::
## Place multiple pages onto one page
Learn how to place multiple PDF pages onto a single page using the **[Place multiple pages on one page](../code-samples/pdftools-sdk-toolbox-samples.mdx#place-multiple-pages-on-one-page) sample project.
:::tip Quick start with a code sample
Download the full sample now in **[C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/MultipleUp/Download?technology=C)**, **[C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/MultipleUp/Download?technology=CS)**, **[Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/MultipleUp/Download?technology=Java)**, and **[Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/MultipleUp/Download?technology=Python)**.
Interested in Go, Rust or other programming language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.
:::
---
## Redact(Toolbox)
The Toolbox add-on lets you remove and redact content from an input PDF document so that it is no longer present in the output document. You can remove entire pages or content like text, images, and paths.
You can also apply targeted redaction by removing or replacing individual characters (glyphs) from text.
:::info
This functionality is part of the Toolbox add-on, a separate SDK that you can use with the same license key as the Pdftools SDK. To use and integrate this add-on, review [Getting started with the Toolbox add-on](../../getting-started/toolbox/) and [Toolbox add-on code samples](../code-samples/pdftools-sdk-toolbox-samples.mdx).
:::
## Remove pages
Learn how to remove specific pages from a PDF document using the [Remove pages from PDF](../../code-samples/pdftools-sdk-toolbox-samples/#remove-pages-from-pdf) code sample.
:::tip Quick start with a code sample
Download the full sample now in **[C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/Split/Download?technology=C)**, **[C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/Split/Download?technology=CS)**, **[Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/Split/Download?technology=Java)**, and **[Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/Split/Download?technology=Python)**.
Interested in Go, Rust or other programming language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.
:::
## Remove content
Learn how to iterate through the PDF to remove specific content using the [Remove White Text from PDF](../../code-samples/pdftools-sdk-toolbox-samples/#remove-white-text-from-pdf) sample project.
:::tip Quick start with a code sample
Download the full sample now in **[C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/RemoveWhiteText/Download?technology=CS)**, **[Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/RemoveWhiteText/Download?technology=Java)**, and **[Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/RemoveWhiteText/Download?technology=Python)**.
Interested in C, Go, Rust or other programming language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.
:::
## Remove individual characters (glyphs)
Learn how to remove individual characters (glyphs) from text in a PDF document using the [Remove glyphs](../../code-samples/pdftools-sdk-toolbox-samples/#remove-glyphs) code sample.
:::tip Quick start with a code sample
Download the full sample now in **[C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/RemoveGlyphs/Download?technology=CS)**, **[Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/RemoveGlyphs/Download?technology=Java)**, and **[Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/RemoveGlyphs/Download?technology=Python)**.
Interested in C or other language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/), and we'll add it to our samples backlog.
:::
---
## Validate PDF documents
With the Pdftools SDK, you can validate PDF documents according to various PDF specifications.
The Pdftools SDK lets you validate the following standards:
| PDF | PDF/A |
| --------------------- | --------------------- |
| PDF Reference 1.3-1.6 | PDF/A-1 (ISO 19005-1) |
| PDF 1.7 (ISO 32000-1) | PDF/A-2 (ISO 19005-2) |
| PDF 2.0 (ISO 32000-2) | PDF/A-3 (ISO 19005-3) |
You can verify PDF documents in accordance with the ISO standard for PDF and also PDF/A for long-term archiving, as well as to a specific conformance level.
Additional verification tests such as checking the version number of the PDF document are also possible. You can also verify conformance to internal directives; for example, use of the right color or use of the right fonts and other specifications. You can check the conformity of individual documents and entire archives.
With the Pdftools SDK, you can:
- Perform PDF conformance in terms of lexical, syntactic, and semantic checks
- Get a detailed or summarized report (log file):
- Get detailed error descriptions: number, type, description, PDF object, page number
- Classify by error, warning, and information
- Cancel validation automatically when the first error is encountered
- Determine the claimed conformance of the document
- Validate conformance to corporate directives defined in custom profile
## Conformance levels
**[Conformance levels](conformance-levels.mdx)** are determined by the PDF standard. Within the PDF/A specification standards, the following conformance levels are supported:
- B (Basic)
- U (Unicode, only PDF/A-2 and PDF/A-3)
- A (Accessibility)
## Validation checks
When you validate a PDF document with the Pdftools SDK, different **[lexical, syntactic, and semantic validation checks](validation-checks.mdx)** are performed according to the PDF version and conformance level.
## Validation reports
You can determine how you want to receive the results of the document validation process. You can choose the reporting level: either a detailed report or a summary of error reports. The description includes every detail such as frequency, page number, or PDF object number. Verification of internal specifications (e.g. standard image resolution) can occur at the same time.
:::tip Get started
Learn **[how to validate a PDF document](validate-a-pdf.mdx)** for conformance with a PDF version, or a PDF/A standard and level.
:::
---
## Conformance levels
Conformance levels apply to [PDF/A documents](/docs/knowledge/pdf-standards#pdfa---archive) only.
A conformance level defines the quality requirements for the PDF document's content.
There are three conformance levels:
1. [B (Basic)](#level-b---basic)
2. [U (Unicode)](#level-u---unicode)
3. [A (Accessibility)](#level-a---accessibility)
The conformance levels are incremental, meaning that the subsequent level includes the requirements of the previous level and other additional requirements. For example, all level U documents are also valid level B documents.
Each PDF/A document has a claimed conformance level. The Pdftools SDK validates this level by performing specific [validation checks](validation-checks.mdx).
For example, only PDF/A documents that claim to have Level U conformance (which can be either PDF/A-2 or PDF/A-3) are checked to determine whether they contain alternate descriptions of the content where needed.
## Level B - Basic
Level B conformance determines the visual integrity of the document. It guarantees clear, long-term visual reproduction of static content in the PDF document. This is the default conformance level for all PDF/A conforming documents.
## Level U - Unicode
Level U conformance guarantees the searchability of text within the PDF. Unicode text is copied to the output file, allowing it to be extracted later if required. This is for digitally created PDF/A documents and documents scanned using optical character recognition (OCR).
This conformance level only applies to PDF documents that conform to [PDF/A-2](/docs/knowledge/pdf-a/#pdfa-2) and [PDF/A-3](/docs/knowledge/pdf-a/#pdfa-3).
## Level A - Accessibility
Level A determines the semantic correctness and structure of the PDF/A document. In other words, it preserves the document's logical structure and content text stream in natural reading order. It also ensures that conforming files can be accessed by devices used by physically impaired users such as screen readers.
This conformance level only applies to PDF documents that conform to [PDF/A-2](/docs/knowledge/pdf-a/#pdfa-2) and [PDF/A-3](/docs/knowledge/pdf-a/#pdfa-3).
---
## Reporting levels for validation
{/*HOW TO ON HOW TO CONFIGURE THE VALIDATION REPORTING LEVELS */}
---
## Validate PDF document
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
Validate a PDF document for conformance with a PDF version, or a PDF/A standard and level.
When standard violations are encountered, you get detailed information about the type and location of the violation.
:::tip Quick start with a code sample
Download the full sample in **[C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/ValidateSimple/Download?technology=C)**, **[C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/ValidateSimple/Download?technology=CS)**, **[Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/ValidateSimple/Download?technology=Java)**, and **[Visual Basic](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/ValidateSimple/Download?technology=VB)**.
:::
**Steps to validate a document**:
1. [Reading the input document](#reading-the-input-document)
2. [Creating a Conformance object](#creating-a-conformance-object)
3. [Creating a Validator object](#creating-a-validator-object)
4. [Running the Validate process](#running-the-validate-process)
5. [Full example](#full-example)
---
:::note Before you begin
You need to **[initialize the library](/docs/licenses/products/pdf-tools-sdk-license/#activate-the-pdftools-sdk-license)**.
:::
## Reading the input document
First you need to read the PDF document you want to validate. To do this, load the input document from the file system into a read-only input `Document`.
This `Document` can then later be passed to the `Converter`.
```csharp
// Open image document
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);
```
```java
// Open input document
FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
com.pdftools.pdf.Document inDoc = com.pdftools.pdf.Document.open(inStr);
```
## Creating a Conformance object
The document validation process begins with the creation of a `Conformance` object.
The `Conformance` object defines the PDF version, or the PDF/A standard and level, against which the document is validated.
:::info
The checks performed are determined by the PDF version or PDF/A standard and conformance level.
For more information on the checks performed by the Pdftools SDK, see **[Validation checks](validation-checks.mdx)**.
:::
This example uses the PDF/A-2 standard (`2`), with conformance level B (`Conformance.PdfALevel.B`).
```csharp
// Create a conformance object that specifies the PDF/A standard and level against which the document is validated.
var conformance = new Conformance(2, Conformance.PdfALevel.B);
```
```java
// Create a conformance object that specifies the PDF/A standard and level against which the document is validated.
Conformance conformance = new Conformance(new Conformance.PdfAVersion(2, Conformance.PdfAVersion.Level.B));
```
## Creating a Validator object
The `Validator` object validates the standards conformance of the input PDF document against the PDF version, or the PDF/A standard and level, defined in the `Conformance` object.
When the Validator finds standard violations, it emits `Error` events that provide detailed information about the type of error and where the error occurred in the PDF document.
A handler function can listen to the `Error` event and execute business logic based on the information contained in it.
```csharp
// Create a Validator object and attach an Error event handler.
// In this example we simply write the validation data to the console, but more complex business logic may be implemented based on the category, location, or other attributes of the validation error.
var validator = new Validator();
validator.Error += (s, e) => Console.WriteLine("- {0}: {1} ({2}{3})", e.Category, e.Message, e.Context, e.PageNo > 0 ? " " + e.PageNo : "");
```
```java
// Create a Validator object and attach an Error event handler.
// In this example, the validation data is written to the console, but more complex business logic may be implemented based on the category, location, or other attributes of the validation error.
Validator validator = new Validator();
validator.addErrorListener(
(Validator.Error error) ->
System.out.format("- %s: %s (%s%s)%n", error.getCategory(), error.getMessage(), error.getContext(), error.getPageNo() > 0 ? String.format(" on page %d", error.getPageNo()) : "")
);
```
## Running the Validate process
After creating the `Conformance` and `Validator` objects, the final step is to call the `Validate` method.
The output of this method is a `ValidationResult` which provides information about the conformance of the input document to the PDF version, or the PDF/A standard and level, that is defined in the `Conformance` object.
If a `Conformance` object is not passed in the `ValidatorOptions`, the `Validate` process instead validates the conformance of the input document against the document's _claimed conformance_.
The _claimed conformance_ is the level of conformance that is stored internally within the input document.
:::info
The input document must be a **valid PDF file format**.
Otherwise, the validation process fails.
:::
```csharp
// Validate the PDF/A standard and level of the document against the defined Conformance level.
var options = new ValidationOptions() { Conformance = conformance };
var result = validator.Validate(inDoc, options);
// Write the result of the Validate method to the console.
Console.WriteLine("Document conforms to " + result.Conformance.ToString() + ": " + result.IsConforming);
```
```java
// Validate the PDF/A standard and level of the document against the defined Conformance level.
ValidationOptions options = new ValidationOptions();
options.setConformance(conformance);
ValidationResult result = validator.validate(inDoc, options);
// Write the result of the Validate method to the console.
System.out.println("Document conforms to " + result.getConformance().toString() + ": " + result.getIsConforming());
```
Here's an example of the output that is generated by this sample code:
```
- Metadata: The key Metadata is required but missing. (catalog)
- Color: A device-specific color space (DeviceRGB) without an appropriate output intent is used. (content of page 1)
Document conforms to PDF/A-2b: False
```
## Full example
```csharp
// Open the PDF document to validate
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);
// Create a conformance object that specifies the PDF/A standard and conformance level against which the document is validated.
// Here the PDF/A-2 standard with conformance Level B is used.
var conformance = new Conformance(2, Conformance.PdfALevel.B);
// Create a Validator object and attach an Error event handler that simply writes the validation error messages to the console.
var validator = new Validator();
validator.Error += (s, e) => Console.WriteLine("- {0}: {1} ({2}{3})", e.Category, e.Message, e.Context, e.PageNo > 0 ? " " + e.PageNo : "");
// Validate the PDF/A Standard and Level of the document against the defined Conformance level.
var options = new ValidationOptions() { Conformance = conformance };
var result = validator.Validate(inDoc, options);
// Write the result of the Validate method to the console.
Console.WriteLine("Document conforms to " + result.Conformance.ToString() + ": " + result.IsConforming);
```
```java
// Open the PDF document to validate
try (FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
com.pdftools.pdf.Document inDoc = com.pdftools.pdf.Document.open(inStr))
{
// Create a conformance object that specifies the PDF/A standard and level against which the document is validated.
// Here we choose the PDF/A-2 Standard, with conformance Level B.
Conformance conformance = new Conformance(new Conformance.PdfAVersion(2, Conformance.PdfAVersion.Level.B));
// Create a Validator object and attach an Error event handler that simply writes the validation error messages to the console.
Validator validator = new Validator();
validator.addErrorListener(
(Validator.Error error) ->
System.out.format("- %s: %s (%s%s)%n", error.getCategory(), error.getMessage(), error.getContext(), error.getPageNo() > 0 ? String.format(" on page %d", error.getPageNo()) : "")
);
// Validate the PDF/A standard and level of the document against the defined Conformance level.
ValidationOptions options = new ValidationOptions();
options.setConformance(conformance);
ValidationResult result = validator.validate(inDoc, options);
// Write the result of the Validate method to the console.
System.out.println("Document conforms to " + result.getConformance().toString() + ": " + result.getIsConforming());
}
```
---
## Validation checks
The Pdftools SDK performs multiple lexical, syntactic, and semantic checks when validating a PDF document according to an ISO standard or a corporate directive.
The table shows details of the validation checks performed according to the **[specification](/docs/knowledge/pdf-standards)** and **[conformance level](conformance-levels.mdx)**.
| | PDF | PDF/A-1 | PDF/A-2 & PDF/A-3 | Level U | Level A |
| -------------------------------------------------------------------------------------------- | --- | ------- | ----------------- | ------- | ------- |
| **Lexical checks** | | | | | |
| Structure of tokens such as keywords, names, numbers, strings etc. | x | x | x | x | x |
| Structure of the cross-reference table | x | x | x | x | x |
| File positions in the trailer dictionary, cross reference table, etc. | x | x | x | x | x |
| Whether a referenced object has the correct object and generation number | x | x | x | x | x |
| Length attribute of stream objects | x | x | x | x | x |
| No header offset | | x | x | x | x |
| Contains a binary marker | | x | x | x | x |
| **Syntactic checks** | | | | | |
| Structure of dictionaries, arrays, indirect objects, streams, etc. | x | x | x | x | x |
| Compression errors, e.g. CCITT, JPEG, Flate, etc. | x | x | x | x | x |
| Errors in embedded font programs | x | x | x | x | x |
| Errors in ICC color profiles | x | x | x | x | x |
| **Semantic checks** | | | | | |
| Required entries in dictionaries, e.g. width entry in an image dictionary | x | x | x | x | x |
| Inherited attributes | x | x | x | x | x |
| Value of the parent entries in dictionaries, e.g. page objects | x | x | x | x | x |
| Type of the dictionary entry's value, e.g. integer, string, name | x | x | x | x | x |
| Whether the object must be indirect or direct, e.g. a page object must be an indirect object | x | x | x | x | x |
| Order of operators in content streams | x | x | x | x | x |
| Number of operands of the operators | x | x | x | x | x |
| Type of operands of the operators | x | x | x | x | x |
| Value ranges of the operands | x | x | x | x | x |
| Unknown referenced resources | x | x | x | x | x |
| Operand stack overflow and underflow | x | x | x | x | x |
| Inconsistent information, e.g. if an image has a stencil mask and soft mask at the same time | x | x | x | x | x |
| Conformance to implementation limits defined by the PDF Reference | x | x | x | x | x |
| No unredered XFA forms | x | x | x | x | x |
| Contains a unique file identifier | | x | x | x | x |
| Contains document metadata | | x | x | x | x |
| Contains embedded font programs where needed | | x | x | x | x |
| Contains character to glyph mapping (encoding) information for the fonts | | x | x | x | x |
| Contains an output intent if needed | | x | x | x | x |
| No encryption | | x | x | x | x |
| No LZW and non-standard filters | | x | x | x | x |
| No JavaScript | | x | x | x | x |
| No unallowed annotations | | x | x | x | x |
| No unallowed actions | | x | x | x | x |
| No form fields that are generated on the fly | | x | x | x | x |
| No embedded PostScript code | | x | x | x | x |
| No invisible, hidden or non-printable annotations | | x | x | x | x |
| No device-specific color spaces | | x | x | x | x |
| No unknown rendering intents | | x | x | x | x |
| No image interpolation | | x | x | x | x |
| No externally referenced information (external streams, reference XObjects, etc.) | | x | x | x | x |
| No Open Print Interface (OPI) information | | x | x | x | x |
| No alternate images | | x | x | x | x |
| No color transfer and half-toning functions | | x | x | x | x |
| No JPX | | x | x | x | x |
| No layers | | x | x | x | x |
| No transparency | | x | x | x | x |
| No embedded files | | x | x | x | x |
| No XRef streams | | x | x | x | x |
| Conformity of metadata | | x | x | x | x |
| PDF/A conformance of embedded files | | | x | x | x |
| Consistency of spot colors | | | x | x | x |
| Contains Unicode information of fonts where needed | | | | x | x |
| Contains logical structure information (tagging) | | | | | x |
| Contains alternate descriptions of content (replacement text) where needed | | | | | x |
---
## PDF Viewer SDK
Integrate a comprehensive PDF viewer with editing capabilities into your web applications. The PDF Viewer SDK is a development library for TypeScript compatible with multiple frameworks and browsers.
## Functionality
With the PDF Viewer SDK, you can work with PDFs directly on the client, without the need for a server-side PDF library. The PDF Viewer SDK provides the following functionality:
- View PDF files.
- Search PDF files.
- Navigate, and work with PDF files programmatically.
- Add predefined annotations.
The PDF Viewer SDK consists of two npm packages, the PDF Web Viewer and the PDF Web SDK:
- [PDF Web Viewer](#pdf-web-sdk)
- [PDF Web SDK](#pdf-web-sdk)
### PDF Web Viewer
The [PDF Web Viewer](https://www.npmjs.com/package/@pdftools/pdf-web-viewer) lets you implement PDF viewer capabilities with search.
:::tip Get started
Try it out with **[Getting started with the PDF Viewer SDK](./getting-started/README.mdx)**.
:::
### PDF Web SDK
The [PDF Web SDK](https://www.npmjs.com/package/@pdftools/pdf-web-sdk) provides the functionality required by the PDF Viewer SDK package with some additional features.
You can use it to implement a viewer with highly customizated experience or to automate processes around your documents programmatically, directly from your TypeScript project without the need for a GUI.
It serves also as the SDK layer for the underlying web assembly that contains the SDK logic and is both consumed by the PDF Web Viewer and the PDF Web SDK.
:::tip Learn about advanced functionality
Implement more complex use cases or build your own custom viewer using the advanced functionality of the PDF Web SDK. For more information, review **[advanced functionality](./guides/README.mdx)**.
:::
### License overview
The following table explains the pricing and feature offering available for various license types of the PDF Viewer SDK:
No license
Free view-only
Trial
Professional
Business
Enterprise
How to
No license key is need
Contact sales
Contact sales
Contact sales
Contact sales
Contact sales
Watermark
Yes
No
No
No
No
No
Feature sets
View-only
View-only
All
Select one
Select three
All
Domains
-
One
On demand
One
Three
On demand
Maximum concurrent users
100
100 extensible
100 extensible
100 extensible
1,000 extensible
Contract based
## Supported languages and frameworks
The PDF Viewer SDK is provided in TypeScript and compatible with the following programming languages, libraries, and frameworks:
- TypeScript
- JavaScript
- React
- Angular
## Supported browsers
The PDF Viewer SDK is tested with and supported for the following browsers:
- Chrome 63+
- Edge 41+
- Firefox 55+
- Safari 11.0.3+
## Supported PDF versions
The PDF Viewer SDK supports the following PDF versions:
| Version | Standard |
| ------------ | ------------------------------------------------------ |
| PDF 1.x | PDF Reference 1.3 - 1.6 |
| PDF 1.7 | PDF 1.7 / ISO 32000-1 |
| PDF 2.0 | PDF 2.0 / ISO 32000-2 |
| PDF/A-1a | PDF/A-1a / ISO 19005-1 / Level A conformance |
| PDF/A-1b | PDF/A-1b / ISO 19005-1 / Level B conformance |
| PDF/A-2a | PDF/A-2a / ISO 19005-2 / Level A conformance |
| PDF/A-2b | PDF/A-2b / ISO 19005-2 / Level B conformance |
| PDF/A-2u | PDF/A-2u / ISO 19005-2 / Level U conformance |
| PDF/A-3a | PDF/A-3a / ISO 19005-3 / Level A conformance |
| PDF/A-3b | PDF/A-3b / ISO 19005-3 / Level B conformance |
| PDF/A-3u | PDF/A-3u / ISO 19005-3 / Level U conformance |
| FDF | included in above standards |
:::note
When saving changes, the PDF Viewer SDK saves the document in the same PDF version as the original file you opened.
To convert documents between PDF versions, please use the:
- [Pdftools SDK](/docs/pdf-tools-sdk/)
- [Conversion Service](/docs/conversion-service/)
:::
---
## PDF Viewer SDK architecture
The PDF Viewer SDK architecture consists of two interconnected npm packages, where the top package builds upon the functionality of the base package. The top package is the PDF Web Viewer package, which provides core viewer capabilities for rendering and interacting with PDF documents. At the base level is the PDF Web SDK package, which provides the necessary functionality for the PDF Web Viewer package. It also includes additional APIs and advanced features, offering a comprehensive toolkit for viewing and working with PDFs that you can implement into your application. However, PDF Viewer SDK is a ready-to-use package, while implementing the PDF Web SDK requires significant development effort compared to the full PDF Viewer SDK.
| Layer | Name | npm package | API reference |
| ----: | ------------------------------------ | ---------------------------------------------------------------------------------- | ------------------------------------------- |
| 1 | [PDF Web Viewer](../README.mdx#pdf-web-viewer) | [@pdftools/pdf-web-viewer](https://www.npmjs.com/package/@pdftools/pdf-web-viewer) | [Viewer API reference](./viewer/index.md) |
| 2 | [PDF Web SDK](../README.mdx#pdf-web-sdk) | [@pdftools/pdf-web-sdk](https://www.npmjs.com/package/@pdftools/pdf-web-sdk) | [PDF Web SDK API reference](./web-sdk/index.md) |
The following chart gives an overview of the most important components in the PDF Viewer SDK and the PDF Web SDK.
Refer to the following sections for more details.
## PDF Web Viewer
The PDF Viewer SDK is a ready-to-use component that can easily be integrated into your application.
:::note
Learn how to [get started](../getting-started/README.mdx).
:::
### PdfToolsViewer component
The `PdfToolsViewer` is a class that provides a comprehensive PDF viewing experience. To use it, follow these steps:
1. Create an instance of the viewer:
```typescript
const viewer = new PdfToolsViewer();
```
2. Initialize the class with the configuration options and a container element:
```typescript
await viewer.initialize(config, containerElement);
```
The `PdfToolsViewer` component offers:
- Document viewing with configurable accessibility features
- Annotation capabilities (add, update, delete) with event listeners
- Navigation controls (go to specific page, next/previous page)
- View manipulation (rotation, zoom)
- Component visibility management
- Custom button behavior overrides
- License-based functionality
Rather than returning an element, the `PdfToolsViewer` component attaches itself to the container you provided and exposes an API for interacting with the PDF document and the viewer interface.
## PDF Web SDK
The PDF Web SDK operates on a higher level of abstraction than the PDF Viewer SDK but also provides more advanced features.
:::note
Learn how to use the PDF Web SDK, for example to [view a document](../guides/document-view.mdx).
:::
The PDF Web SDK provides several namespaces encapsulating different functionalities:
### Namespaces
1. **Core**: Core components, functionalities and utilities used by the API.
2. **Pdf**: Contains logic necessary for working with PDF files, such as opening, closing, editing, or saving PDF documents. These operations provide the foundational functionality for interacting with PDF files within the API.
1. **Annotations**: Types describing PDF annotations along with the properties related to each subtype.
2. **Drawing**: Types related to drawing or rendering PDF content, such as drawing shapes, lines, or text on a PDF page.
3. **Forms**: Types related to handling PDF forms, such as filling out form fields, extracting form data, or validating form entries.
4. **Geometry**: Types related to geometric operations on PDF elements, such as calculating areas, distances, or transformations.
5. **Search**: Types related to searching for specific content within a PDF document, such as text search or advanced search capabilities.
3. **UI**: Components or functions related to building a user interface (UI) for interacting with the PDF document.
### Important components
There are several components which are commonly used when interacting with a PDF document.
#### PdfToolsWebSdk
Singleton object named [`pdfToolsWebSdk`](./web-sdk/variables/pdfToolsWebSdk.md) is used to initialize PDF Web SDK.
Singleton instance of this object is created internally and is available for public access.
#### Pdf.Controller
[`Pdf.Controller`](./web-sdk/namespaces/Pdf/classes/Controller.md) class is used for managing documents inside the PDF Web SDK.
It should be instantiated and reused for managing multiple documents.
#### Pdf.Document
[`Pdf.Document`](./web-sdk/namespaces/Pdf/classes/Document.md) class is used for representing a PDF document inside the PDF Web SDK.
Instances of this object are created internally and are available for access through [`Pdf.Controller`](./web-sdk/namespaces/Pdf/classes/Controller.md).
#### Pdf.Page
[`Pdf.Page`](./web-sdk/namespaces/Pdf/classes/Page.md) class is used for representing a page inside a PDF document.
Instances of this object are created internally and are available for access through [`Pdf.Document`](./web-sdk/namespaces/Pdf/classes/Document.md) property called `pages`.
#### Pdf.AnnotationManager
[`Pdf.AnnotationManager`](./web-sdk/namespaces/Pdf/classes/AnnotationManager.md) class is a central interaction hub designed to handle annotation-related operations within a document.
It serves as a bridge between user interactions and the underlying document structure, facilitating dynamic changes to annotations based on user actions.
It's available per document through [`Pdf.Document`](./web-sdk/namespaces/Pdf/classes/Document.md) property called `annotations`.
#### UI.DocumentView
[`UI.DocumentView`](./web-sdk/namespaces/UI/classes/DocumentView.md) class is used for managing the presentation and interaction with a PDF document within a container element.
It should be constructed with a reference to a container element and initialized with a [`Pdf.Document`](./web-sdk/namespaces/Pdf/classes/Document.md) in order to create an interactive preview of the PDF document.
---
## Customize the PDF Viewer SDK
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
{/* TODO https://smallpdf.atlassian.net/browse/PDFTVIEWER-778 */}
---
## Getting started with the PDF Viewer SDK
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
Get up and running with the PDF Viewer SDK.
This guide walks you through the steps to integrate the [the ready-to-use viewer](../README.mdx#pdf-web-sdk) into your application.
:::tip
You can also follow this guide if you are starting with a project from scratch. For this, all you need is a blank folder.
:::
## Prerequisites
To install the package, use a package manager such as npm or yarn.
## Get started with a sample project
Learn how to run the PDF Viewer SDK sample:
### Compile and run the sample
1. Download or clone the [sample repository](https://github.com/pdf-tools/pdf-web-viewer-samples/tree/main).
1. From the root of the repository, navigate to a sample at the following path:
```
examples/vanilla-typescript/view-pdf
```
1. Git checkout to the branch with the latest version:
```
git checkout 5.10.0
```
1. Install dependencies:
```
npm install
```
1. Build the project:
```
npm run build
```
1. Run the server:
```
npm run dev
```
1. Open [`http://localhost:4567/`](http://localhost:4567/) in your browser.
:::tip samples
Run other samples in the same way. Review the `/examples` directory for more samples in the downloaded or cloned [sample repository](https://github.com/pdf-tools/pdf-web-viewer-samples/tree/main).
:::
## Integrate the SDK into your application
Integrate and initialize the PDF Viewer SDK into your application by following the instructions in the next sections.
### Add the SDK to your project
In your project folder run the following command to install the PDF Web Viewer:
```
npm install @pdftools/pdf-web-viewer
```
### Static assets
PDF Web Viewer comes with static assets and resource files (WebAssembly and JavaScript files) stored in `node_modules/@pdftools/pdf-web-sdk/dist/wasm` sub-directory. To allow proper initialization of the PDF Web Viewer inside of your application, make mentioned files publicly available to the application from a base path (for example: `/pdftools-viewer-sdk`). You can do this automatically or manually depending on your system, see the following sections for more details:
- [Copy static assets automatically](#copy-static-assets-automatically)
- [Copy static assets manually](#copy-static-assets-manually)
#### Copy static assets automatically
Automate the process for development and production using a bundler, to make sure that always the proper assets are used on every build. While copying files manually for prototyping is a viable way, automating this process is recommended.
In React, tools like **Webpack** or **Rollup** are typically used for bundling your application.
Copying of the assets and resource files can be automated using `copy-webpack-plugin`.
This automatically copies the files from `node_modules/@pdftools/pdf-web-viewer/pdftools-web-viewer` to `/pdftools-web-viewer` on every build.
An example of `webpack.config.js`:
```javascript
const CopyWebpackPlugin = require('copy-webpack-plugin');
module.exports = {
// Other Webpack configuration options...
plugins: [
new CopyWebpackPlugin({
patterns: [
{
from: 'node_modules/@pdftools/pdf-web-viewer/pdftools-web-viewer',
to: 'pdftools-web-viewer',
},
],
}),
],
};
```
For more details see [official copy-webpack-plugin documentation](https://webpack.js.org/plugins/copy-webpack-plugin).
Copying of the assets and resource files can be automated using `rollup-plugin-copy`.
This automatically copies the files from `node_modules/@pdftools/pdf-web-viewer/pdftools-web-viewer` to `/pdftools-web-viewer` on every build.
An example of `rollup.config.js`:
```javascript
import copy from 'rollup-plugin-copy';
export default {
// Other Rollup configuration options...
plugins: [
copy({
targets: [
{
src: 'node_modules/@pdftools/pdf-web-viewer/pdftools-web-viewer',
dest: 'pdftools-web-viewer',
},
],
}),
],
};
```
For more details see [official rollup-plugin-copy documentation](https://www.npmjs.com/package/rollup-plugin-copy).
Add the path to the static assets in the assets array of your `angular.json` file.
```json
"assets": [
"src/favicon.ico",
"src/assets",
{
"glob": "**/*",
"input": "node_modules/@pdftools/pdf-web-viewer/pdftools-web-viewer",
"output": "/pdftools-web-viewer/"
}
]
```
For more details, review [official Angular documentation](https://angular.io/guide/workspace-config#asset-config).
In Vue, **Webpack** is typically used for bundling your application.
Copying of the assets and resource files can be automated using `copy-webpack-plugin`.
This automatically copies the files from `node_modules/@pdftools/pdf-web-viewer/pdftools-web-viewer` to `/pdftools-web-viewer` on every build.
An example of `webpack.config.js`:
```javascript
const CopyWebpackPlugin = require('copy-webpack-plugin');
module.exports = {
// Other Webpack configuration options...
plugins: [
new CopyWebpackPlugin({
patterns: [
{
from: 'node_modules/@pdftools/pdf-web-viewer/pdftools-web-viewer',
to: 'pdftools-web-viewer',
},
],
}),
],
};
```
For more details see [official copy-webpack-plugin documentation](https://webpack.js.org/plugins/copy-webpack-plugin).
For details also see [official Vue CLI Webpack configuration documentation](https://cli.vuejs.org/guide/webpack.html#simple-configuration).
Tools like **Webpack** or **Rollup** can be used for bundling your application.
Copying of the assets and resource files can be automated using `copy-webpack-plugin`.
This automatically copies the files from `node_modules/@pdftools/pdf-web-viewer/pdftools-web-viewer` to `/pdftools-web-viewer` on every build.
An example of `webpack.config.js`:
```javascript
const CopyWebpackPlugin = require('copy-webpack-plugin');
module.exports = {
// Other Webpack configuration options...
plugins: [
new CopyWebpackPlugin({
patterns: [
{
from: 'node_modules/@pdftools/pdf-web-viewer/pdftools-web-viewer',
to: 'pdftools-web-viewer',
},
],
}),
],
};
```
For more details see [official copy-webpack-plugin documentation](https://webpack.js.org/plugins/copy-webpack-plugin).
Copying of the assets and resource files can be automated using `rollup-plugin-copy`.
This automatically copies the files from `node_modules/@pdftools/pdf-web-viewer/pdftools-web-viewer` to `/pdftools-web-viewer` on every build.
An example of `rollup.config.js`:
```javascript
import copy from 'rollup-plugin-copy';
export default {
// Other Rollup configuration options...
plugins: [
copy({
targets: [
{
src: 'node_modules/@pdftools/pdf-web-viewer/pdftools-web-viewer',
dest: 'pdftools-web-viewer',
},
],
}),
],
};
```
For more details see [official rollup-plugin-copy documentation](https://www.npmjs.com/package/rollup-plugin-copy).
:::info Copy files differently in PDF Web SDK
In case you are using just the [PDF Web SDK](../README.mdx#pdf-web-sdk) without the [PDF Web Viewer](../README.mdx#pdf-web-viewer) in your project:
1. Copy static assets from `node_modules/@pdftools/pdf-web-sdk/pdftools-web-sdk`.
:::
#### Copy static assets manually
Copy the static assets manually if you have specific requirements within your project that can be difficult to solve with automatic copy by issuing the following steps:
1. Copy the files to a publicly available path.
2. If your project is served through a server, ensure that the server is configured to serve WASM files with the appropriate MIME type (application/wasm).
### Initialize the viewer
When you are finished with the resources setup, initialize the PDF Viewer SDK with the following steps:
1. Create a minimalistic HTML page (for example `index.html`) with a `` element, including a Viewer container. Review the example below:
```html
Document
{/* this element will be used to attach the viewer to it */}
```
1. Create a short TypeScript file that performs the initiliazation of the PDF Viewer SDK:
```typescript
import { PdfToolsViewer } from '../../components/pdftools-viewer';
// create the viewer element
const el = PdfToolsViewer.initialize();
// attach it to the reserved element
const container = document.getElementById('viewer-container');
container.append(el);
```
:::note
By default the PDF Web Viewer looks for static assets in `'./pdftools-web-viewer/'`.
If you configure your project's [static assets](#static-assets) in a different location, provide the location as an argument:
```typescript
const el = PdfToolsViewer.initialize({
path: './pdftools-web-viewer/',
});
```
:::
### Manage license key
The PDF Viewer SDK displays watermarked pages by default. Use a license key to remove the watermark for free. To obtain the license key:
1. Contact sales through the [contact form](https://www.pdf-tools.com/contact/) to obtain the Free View-only license.
When you obtain the license key, include it in the initialize method to remove the watermark.
1. Find the `PdfToolsViewer.init` in the `index.ts` or `index.js`, and include the license key as follows:
```ts
const el = await PdfToolsViewer.initialize({licenseKey: ""});
```
### Open a PDF document
With the ready-to-use viewer, end users can open files using a built-in file-open dialog.
Optionally the file can be opened programmatically from different sources:
```typescript
// open a document from a URL
PdfToolsViewerApi.document.openFromUrl('../pdf/WebViewer_Demo.pdf');
```
```typescript
// load the document content from an arbitrary source
const res = await fetch('http://localhost:3300/pdf/WebViewer_Demo.pdf');
const arrayBuffer = await res.arrayBuffer();
// convert the content to BLOB
const base64 = btoa(
new Uint8Array(arrayBuffer).reduce(
(data, byte) => data + String.fromCharCode(byte),
''
)
);
const bufferData = `data:application/octet-stream;base64,${base64}`;
const blobData = await fetch(bufferData).then((res) => res.blob());
// create a file from the BLOB
const file = new File([blobData], 'WebViewer_Demo.pdf', {
type: 'text/plain',
});
// open the file
PdfToolsViewerApi.document.openFromFile(file);
```
```typescript
// load the document content from an arbitrary source
const res = await fetch('http://localhost:3300/pdf/WebViewer_Demo.pdf');
const arrayBuffer = await res.arrayBuffer();
// convert the content to an in memory array
const uint8array = new Uint8Array(arrayBuffer);
// open the in memory arry
PdfToolsViewerApi.document.openFromMemory(uint8array);
```
### Implement your use case
- Find instructions how to implement specific use cases in the [guides](../guides/README.mdx) section.
- Find more technical information about the PDF Viewer SDK in the [API references](../api-references/README.mdx).
{/*- Play with the PDF Viewer SDK in the [playground](TODO). */}
:::info PDF Web SDK
The PDF Viewer SDK lets you customize some functionalities. If you have specific requirements, you can implement your own PDF viewer using the PDF Web SDK. Implementing the PDF Web SDK allows for greater customization but requires sifnificant development effort than the full PDF Viewer SDK. For more details, review the following sections and pages:
- [PDF Web SDK](../README.mdx#pdf-web-sdk)
- [Advanced functionality](../guides/README.mdx)
:::
---
## Custom implementation guides
import DocCardList from '@theme/DocCardList';
:::info
These guides focus on the advanced functionality of the [PDF Web SDK](../README.mdx#pdf-web-sdk), an underlying layer of the PDF Viewer SDK. If you prefer to test a demo or would like to explore the basic functionalities of this SDK, review [Getting started with the PDF Viewer SDK](../getting-started/README.mdx).
Refer to the API references for more information about the differences between PDF Viewer SDK and PDF Web SDK. [API references](../api-references/README.mdx).
:::
Learn about various advanced functionalities of the PDF Web SDK. Find a guide for your use case by clicking one of the following cards:
PDF Viewer SDK
```
** index.ts **
```typescript
import { pdfToolsWebSdk, Pdf, UI } from '@pdftools/pdf-web-sdk';
async function initialize() {
await pdfToolsWebSdk.initialize({
path: './pdftools-web-sdk/',
});
const container = document.querySelector('#pdftools-web-viewer-container');
const documentView = new UI.DocumentView(container);
const controller = await new Pdf.Controller().initialize();
const pdfDocument = await controller.openDocument({
uri: '/pdf/WebViewer_Demo.pdf',
});
documentView.initialize(pdfDocument);
}
initialize();
```
---
## Manage events
:::info
In this documentation, you can learn how to implement specific features of the PDF Web SDK. If you prefer to test a demo or would like to explore the basic functionalities of this SDK, review [Getting started with the PDF Viewer SDK](../getting-started/README.mdx).
:::
Listen to and programmatically dispatch built-in and custom events with the PDF Web SDK.
The PDF Viewer SDK `EventEmitter` class provides a powerful and typesafe mechanism for managing and dispatching events by classes which are designed to emit events.
By default, there are multiple classes which support events, such as `Pdf.Document`, `Pdf.Page`, `UI.DocumentView`. You can also create custom classes extending `EventEmitter`.
The `EventEmitter` template type describes which events are supported by a concrete class and specifies the expected structure of the provided callback functions.
**This guide explains the following:**
1. [Generic EventEmitter concept](#generic-eventemitter-concept)
1. [Listening to built-in events](#listening-to-built-in-events)
1. [Full example](#full-example)
---
:::note Before you begin
The `EventEmitter` class can be used noth within or outside of the context of the PDF Viewer SDK.
However, if you want to listen to events emitted by or dispatch events to the PDF Viewer SDK, first learn how to work with the PDF Web SDK, for example how to [view a document](./document-view.mdx) or [read document information](./document-information.mdx).
:::
## Generic EventEmitter concept
The `EventEmitter` class makes use of event maps - a type safe approach to define the name and the parameters of supported events.
For example, if you want to define an event named `'sampleEventOccurred'` that takes one parameter of type `number`, you can describe this with an interface like this:
```typescript
interface SampleEventMap {
sampleEventOccurred: (sampleParam: number) => void;
}
```
When now creating an `EventEmitter` using this event map, the `EventEmitter` template type will make the typescript compiler assure, that only suitable event names and handlers are accepted on `addEventListener`, `dispatchEvent`, and `removeEventListener`.
```typescript
import { Core } from '@pdftools/pdf-web-sdk';
// extend EventEmitter using the event map defined above
class SampleEventEmitter extends Core.EventEmitter {}
// Create an instance of class which extends EventEmitter
const eventEmitter = new SampleEventEmitter();
```
Now event function is typesafe, for example:
```typescript
const goodListener = (sampleParam: number) => {
console.log('Sample event occurred', sampleParam);
};
const badListener = (sampleParam: string) => {
console.log('Sample event occurred', sampleParam);
};
// add event listener
// OK
eventEmitter.addEventListener('sampleEventOccurred', goodListener);
// NOT OK: unsupported event name
eventEmitter.addEventListener('sampleEvent', goodListener);
// NOT OK: wrong listener parameters
eventEmitter.addEventListener('sampleEventOccurred', badListener);
// dispatch event
// OK
eventEmitter.dispatchEvent('sampleEventOccurred', [123]);
// NOT OK: unsupported event name
eventEmitter.dispatchEvent('sampleEvent', [123]);
// NOT OK: wrong listener parameters
eventEmitter.dispatchEvent('sampleEventOccurred', ["foo"]);
// remove event listener
// OK
eventEmitter.removeEventListener('sampleEventOccurred', goodListener);
// NOT OK: unsupported event name
eventEmitter.removeEventListener('sampleEvent', goodListener);
// NOT OK: wrong listener parameters
eventEmitter.removeEventListener('sampleEventOccurred', badListener);
```
## Listening to built-in events
Listening to built-in events works exactly as described in the generic concept above.
For each class emitting events you find the definition of the supported events as an event map in the API references, for example:
- [Controller](../api-references/web-sdk/namespaces/Pdf/classes/Controller.md) ➡️ [ControllerEventMap](../api-references/web-sdk/namespaces/Pdf/interfaces/ControllerEventMap.md)
- [Document](../api-references/web-sdk/namespaces/Pdf/classes/Document.md) ➡️ [DocumentEventMap](../api-references/web-sdk/namespaces/Pdf/interfaces/DocumentEventMap.md)
- [DocumentView](../api-references/web-sdk/namespaces/UI/classes/DocumentView.md) ➡️ [DocumentViewEventMap](../api-references/web-sdk/namespaces/UI/interfaces/DocumentViewEventMap.md)
- [Page](../api-references/web-sdk/namespaces/Pdf/classes/Page.md) ➡️ [PageEventMap](../api-references/web-sdk/namespaces/Pdf/interfaces/PageEventMap.md)
## Full example
This full example demonstrates how to react to changes in the `DocumentView` and log them to the console.
```typescript
import { pdfToolsWebSdk, Pdf, UI } from '@pdftools/pdf-web-sdk';
async function initialize() {
await pdfToolsWebSdk.initialize({
path: './pdftools-web-sdk/',
});
const container = document.querySelector('#pdftools-web-viewer-container');
const documentView = new UI.DocumentView(container);
const controller = new Pdf.Controller();
const pdfDocument = await controller.openDocument({
uri: '/pdf/WebViewer_Demo.pdf',
});
const zoomListener = (zoomLevel: number) => {
const percent = number * 100;
console.log(`zoom changed to ${percent}%`);
};
documentView.addEventListener('zoomChanged', zoomListener);
documentView.initialize(pdfDocument);
}
initialize();
```
---
## Release notes(Pdf-web-viewer)
Learn about the changes, additions, and fixes in the PDF Viewer SDK.
## Version 5
### Version 5.10.0
23 October 2025
#### Added
- The PDF Viewer SDK introduces a print dialog with configurable dots per inch (DPI) settings. The viewer now prints PDFs with vector graphics and text preservation, ensuring high-quality printouts, rather than rasterized, low-resolution bitmaps.
- The toolbar and sidebar are now responsive, automatically adapting to smaller screen sizes. On mobile devices, the left toolbar moves to the top under the fixed header, while the viewer hides the sidebar by default to maximize viewing space. Users can access the sidebar through toggle controls when needed.
- Line and arrow annotations now support opacity customization. Users can adjust the opacity level when drawing or creating these annotations for better visual control and document clarity.
#### Fixed
- Touch gesture interactions on mobile devices now work correctly. Users can scroll the canvas using swipe gestures and zoom in or out using pinch gestures across iOS and Android devices.
- Line annotation previews now correctly respect the current zoom level. The preview during creation matches the final annotation size and position at all zoom levels, eliminating visual inconsistencies.
- Fixed a memory leak that occurred when loading and navigating large PDFs. The viewer no longer accumulates excess memory, preventing browser crashes and performance degradation during extended use.
- Cloud annotations (annotations with stylized, scalloped borders) are visible in the annotations panel. They display with the same design and behavior as other annotation types, including the cloud icon, metadata, and clickable navigation.
### Version 5.9.0
3 October 2025
#### Added
- The PDF Viewer SDK now supports line annotations, enabling users to draw straight lines on PDF documents. Users and developers can customize them with colors, thickness, and line patterns for use cases such as directional markings or visual separation.
- Users can now create arrow annotations to point directions to specific elements in PDF documents. These are a type of line annotation with an arrowhead at the start and/or end, useful for reviews, comments, or instructional documents.
- Cloud annotations have been introduced, allowing users to highlight areas with a stylized, scalloped border. Users and developers can customize the border color, fill color, and line width.
- A new annotation-changed event system triggers when users add, modify, or delete annotations. The system includes a reference to the annotation object for inspection and manipulation, with safeguards against recursive triggering.
- The PDF Viewer SDK now includes a dispose method that cleans all viewer resources, including controllers, document views, annotations, and event listeners. As a result, memory leaks are prevented and repeated creation and disposal of viewers without performance issues is enabled.
#### Changed
- Refactored the PDF Viewer SDK API to provide a more powerful, scalable, and easier-to-use interface, simplifying extension and customization.
#### Fixed
- You can now load viewer instances simultaneously. Each instance is isolated from others, preventing interference and conflicts.
- Previously, reopening a document with an active plugin (for example, text markup or notes) caused deactivation issues. This release resolves these issues, allowing you to activate and deactivate plugins reliably. As a result, plugin activation and deactivation now work correctly across document sessions.
### Version 5.8.0
16 September 2025
#### Added
- With this release, the PDF Viewer SDK presents a new annotation viewing panel.
- Viewer users can now navigate documents using a clickable list of headings (also known as the document outline, or bookmarks).
#### Fixed
- As of this release, the PDF Viewer SDK delivers improved support for large files. This was achieved by raising memory limits and resolving a related processing issue.
### Version 5.7.0
03 July 2025
#### Changed
- You can now work with multiple interactive layers simultaneously, instead of being limited to just one. This enhancement enables the creation of more dynamic and layered PDF experiences.
#### Fixed
- The worker thread is now properly cleaned up when the `WorkerController` is disposed, preventing unnecessary background activity.
- Page re-rendering now functions correctly after annotations are moved across pages, ensuring that changes appear as expected.
- The `pdfToolsWebSdk.version` property previously returned the value `dev`. As of this update, the `pdfToolsWebSdk.version` property returns the correct version string.
### Version 5.6.0
09 June 2025
#### Added
- Viewer users can now add text stamp annotations by choosing from the predefined set of stamps, including texts such as **Approved**, **Confidential**, **Draft**, and many others.
- A loading spinner is displayed while the PDF Viewer SDK is opening a file to provide a progress indicator.
- As of this update, viewer users can create text markup annotation gestures on mobile devices.
#### Fixed
- Previously, users could not scroll upward when using the fit-to-page mode. This issue has been resolved.
- The background visual for the zoom slider was missing. With this update, the correct background is now restored.
- The `pdfToolsWebSdk.version` property previously returned value `undefined`. As of this update, the `pdfToolsWebSdk.version` property returns the correct version string.
### Version 5.5.0
29 April 2025
#### Added
- The PDF Viewer SDK lets you implement text markup annotations, enabling users to highlight, underline, strike through, and create squiggly line annotations in documents.
- With this update, the PDF Viewer SDK includes an accessibility layer, improving usability for users who rely on assistive technologies. For more information, review the [Enable accessibility layer](./standard-implementation/customize-viewer.mdx#enable-accessibility-layer) section.
- You can add custom headers using HTTP requests when opening a document, improving integration flexibility. For more information, review the [Provide custom HTTP headers when opening a document](./standard-implementation/customize-viewer.mdx#provide-custom-http-headers-when-opening-a-document) section.
- As of this update, the viewer users can hide the annotation bar.
#### Fixed
- Previously, under certain circumstances, a part of a sticky note bar remained displayed upon closing a sticky note. This update resolves the described issue.
- To improve consistency and maintainability of the component's styling, the CSS variables referenced in the styles are now defined adequately with default values.
### Version 5.4.0
26 March 2025
#### Added
- You can now drag sticky note annotations between pages.
- You can now customize the color theme of the PDF Viewer SDK using the following set of 6 CSS variables:
- `--background-color`
- `--color-text-primary`
- `--color-text-secondary`
- `--hover-background-color`
- `--secondary-color`
- `--active-color`
#### Changed
- In the PDF Viewer SDK API:
- Functions responsible for emitting events have been renamed from `eventname()` to `emitEventname()`. As a result, it is clear that the purpose of these functions is to emit events.
- The parameter name for callback functions has been changed from `fn` to `callback`.
- New PDF Web SDK API methods simplify conversion between PDF and document viewpoints, making custom layer implementation easier. For more details, review [Page](./api-references/web-sdk/namespaces/Pdf/classes/Page.md) class API reference.
#### Fixed
- An issue where the cursor was stuck in the loading state has been resolved.
- Previously, the thumbnails would not have been updated if the document had been changed. With this release, the issue has been resolved.
### Version 5.3.0
27 February 2025
#### Added
- You can now interact with link annotations that navigate you to external resources or specific locations within the PDF.
- Developers can now implement custom text markup annotations through the PDF Web SDK. This feature lets you create, edit, and delete highlights, underlines, squiggly lines, and strikethroughs, as well as customize their color. For more information, review [Class: TextMarkupAnnotation](./api-references/web-sdk/namespaces/Pdf/namespaces/Annotations/classes/TextMarkupAnnotation.md) in the PDF Wev SDK API references.
### Version 5.2.0
7 February 2025
#### Added
- You can now add, create, edit, and delete sticky note annotations. A new annotation contextual menu lets you add text, edit the color of annotations, and lock the annotation to prevent accidental edits.
#### Changed
- With this update, the new layering mechanism separates search and text selection. As a result, the performance of the PDF Viewer SDK is now improved.
### Version 5.1.1
21 January 2025
#### Added
- You can now override the save button behavior to initiate custom actions. For more information, review the [Modify save button behavior](./standard-implementation/customize-viewer.mdx#modify-save-button-behavior) section.
#### Changed
- Previously, when you opened a corrupt PDF, the PDF Viewer SDK auto-repair feature tried to fix the corrupted file. As a consequence, fixing the file could invalidate some digital signatures. With this update, you can disable the auto-repair with a boolean to prevent unwanted modifications of the original documents. For more information, review the [Disable auto-repair feature](./standard-implementation/customize-viewer.mdx#disable-auto-repair-feature) section.
### Version 5.1.0
18 November 2024
#### Added
- The PDF Viewer SDK can now navigate you to the selected search result.
#### Fixed
- PDF Viewer SDK Licensing is now pointing to the correct endpoint.
- Before this update, there was a race condition when initializing the PDF Viewer SDK with the Angular framework. With this update, the issue was fixed.
- Under certain circumstances, the PDF Viewer SDK could capture events outside of the canvas. As of this update, the underlying issue has been fixed, and the canvas size is the only space where you can capture events.
- The API references and their generation process have been updated.
### Version 5.0.0
11 September 2024
#### Added
- The PDF Viewer SDK architecture was rewritten entirely. As a result, the SDK now consists of two packages:
- PDF Web Viewer: An SDK that lets you implement PDF viewer capabilities with search.
- PDF Web SDK: The functionality the PDF Web Viewer requires and additional features that let you completely customize the SDK.
It's recommended that you try the PDF Web Viewer first. The PDF Web Viewer lets you customize some functionalities. You can implement your own PDF viewer using the PDF Web SDK if you have specific requirements. Implementing the PDF Web SDK lets you create a customized viewer from scratch but requires more development effort than the full PDF Viewer SDK.
- The PDF Web Viewer is now working on both desktop and mobile.
- Only the free Viewer-only version is available.
## Previous versions
:::warning Version incompatibility
While the PDF Viewer SDK version 5 introduces new and improved functionality, it is also incompatible with implementations of the PDF Viewer SDK version 4.
Hence this page provides release notes for version 5.0.0 and above. For previous release notes, refer to the [version 4 release notes](../../pdf-web-viewer_versioned_docs/version-4/release-notes.mdx).
:::
---
## Standard implementation overview
import DocCardList from '@theme/DocCardList';
Learn about the standard functionality of the PDF Viewer SDK and customization capabilities. Find a guide for your use case by clicking one of the following cards:
Developer guide
API
Send API calls to validate and fix PDFs.
Developer guide
:::note Documentation for other versions
PDF Analysis & Repair is no longer available as a service. For existing customers, access the [Service version developer guide](https://www.pdf-tools.com/public/downloads/manuals/PdfRepairService.pdf).
:::
---
## PDF Extract documentation
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
:::info Extract with Pdftools SDK
This product has been replaced by the **[Pdftools SDK](../../pdf-tools-sdk/)**. You can find this functionality specifically in the **Toolbox add-on**.
:::
[PDF Extract](https://www.pdf-tools.com/products/manipulation/pdf-extract/) is a robust SDK that lets you extract
content and metadata, including fonts, images, and text. You extract and query various attributes and page content from
a PDF document.
Shell
Use the command line to transform PDF content into useable
information.
Developer guide
API
Send API calls to transform PDF content and metadata into useable
information.
Developer guide
---
## Code samples for PDF to Image Converter
:::caution Product update
This product has been replaced by the **[Pdftools SDK](../../pdf-tools-sdk/convert/)**.
:::
PDF to Image Converter lets you transform PDF documents into single page or multi-page raster images such as TIFF or JPEG. Here you'll find some examples of how to integrate the code in your development.
import { CodeSamples } from '@site/src/components/CodeSamples'
true
-cms
Set the color management engine
Always none
-dmr
Resolution for monochrome images
See -dr
-dmt
Threshold for monochrome images
See -dt
-dcr
Resolution for color images
See -dr
-dct
Threshold for color images
See -dt
-dbr
Resolution for bitonal images
Not supported
-dbt
Threshold for bitonal images
Not supported
-dr
Resolution in DPI
-dr
-dt
Threshold in DPI
-dt
-fb
Compression types for bitonal images
Preselected based on optimization profile
-fc
Compression types for color and grayscale images
-as
-ff
Force re-compression
Not supported
-fi
Compression types for indexed (paletted) images
Preselected based on optimization profile
-fn
File name
Input file is inferred from command syntax
-ft
Force compression types
Not supported
-fv
Minimum PDF version
Not supported
-h
Dithering mode for bitonal images
Not supported
-id
Set value in the document information dictionary
-t <title>
-a <author>
-s <subject>
-k <keyword1,keyword2> etc.
-c <creator>
-cd <creation date>
-md <modification date>
-lf
List fonts
Not supported
-li
List images
Not supported
-lk
Set license key
-lk
-m
Merge embedded font programs
-nmf to disable
-ml
Compression type for MRC layers
-as
-mlq
Image quality for MRC layers
-lq
-mlr
Resolution in DPI for MRC layers
-lr
-mm
Compression type for the MRC mask
Always eComprAttemptJBIG2
-mp
Compression type for MRC cutout pictures
Not supported
-o
Owner password
-opw <perms>
-oc
Clip images
Always true
-od
Optimize resources
Always true
-ol
Linearize only
Not supported
-or
Remove redundant objects
Always true
-ow
Optimize for the web
Use optimize-web command
-owa
Optimize for the Web automatically
Use optimize-web command
-p
Permission flags
See <perms> parameter of -opw
-pr
Set an optimization profile
Profile is inferred from command
-pw
Read an encrypted PDF file
-pw
-q
Compression quality
-q
-rc
Reduce image color complexity
Always true
-ri
Remove images
Always false
-rf
Remove embedded font program
Not supported
-rs
Remove embedded standard fonts
-rsf
-s
Subset fonts
Always true
-sa
Strip article threads
-kat (keep article threads)
-sf
Flatten and strip form fields and annotations
-csa and -csf
-sff
Flatten and strip form fields
-csf
-sfl
Flatten and strip link annotations
-csa
-sfa
Flatten and strip other annotations
-csa
-sfs
Flatten appearances of signature fields
-csa
-sia
Flatten and strip invisible annotations
-csa
-si
Strip alternate images
-rai
-sm
Strip metadata
-km (keep metadata)
-so
Strip output intents
-roi
-sp
Strip page piece info (private application data)
-kpi (keep piece info)
-ss
Strip document tree structure
-kst (keep document tree structure)
-st
Strip thumbnails
-kt (keep thumbnails)
-sw
Strip spider (web capture) info
Always true
-u
User password
-upw
-v
Verbose mode
-verbose
-xf
Extract fonts
Not supported
-xi
Extract images
Not supported
---
## Code samples for PDF to PDF/A Converter
import { CodeSamples } from '@site/src/components/CodeSamples'
:::caution Product update
This product has been replaced by the **[Pdftools SDK](../../pdf-tools-sdk/archive/)**.
:::
PDF to PDF/A Converter converts PDFs to PDF/A format. Here you'll find some examples of how to integrate the code in your development.
Developer guide
API
Send API calls to transform PDF content and metadata into useable
information.
Developer guide
:::tip See it in action!
Check out the **[code samples](pdf-printer-code.mdx)** for examples on how to use PDF Printer.
:::
:::note Documentation for other versions
PDF Printer is no longer available as a service. For existing customers, access the [Service version developer guide](https://www.pdf-tools.com/public/downloads/manuals/PdfPrinterService.pdf).
:::
---
## Code samples for PDF Security
import { CodeSamples } from '@site/src/components/CodeSamples'
:::caution Product update
This product has been replaced by the **[Pdftools SDK](../../pdf-tools-sdk/sign-and-secure/)**.
:::
With PDF Security, you can digitally sign multiple PDF documents using online signing services and local certificates. Here you'll find some of some examples of how to integrate the code in your development.
\`
Pass the license key to activate the product.
An empty string may be passed to use a default license which will watermark all pages.
#### Default Value
`''`
***
### licenseUrl?
> `optional` **licenseUrl**: `string`
Url to the License Gateway url
***
### logLevel?
> `optional` **logLevel**: [`LogLevel`](../namespaces/Core/enumerations/LogLevel.md)
The log level used by the Pdftools PDF Web SDK
#### Default Value
`LogLevel.ERROR`
***
### logger?
> `optional` **logger**: `ILogger`
Logger class. Must implement ILogger
#### Default Value
`window.console`
***
### path?
> `optional` **path**: `string`
Path where all Pdftools PDF Web SDK resources are located.
#### Default Value
`'./pdftools-web-sdk/'`
***
### producerSuffix?
> `optional` **producerSuffix**: `string`
Producer suffix used in the PDF document
#### Default Value
`Pdftools`
---
## Class: EventEmitter\
EventEmitter is a class designed for managing and dispatching events.
## Extended by
- [`AnnotationManager`](../../Pdf/classes/AnnotationManager.md)
- [`Page`](../../Pdf/classes/Page.md)
- [`Controller`](../../Pdf/classes/Controller.md)
- [`SearchExecution`](../../Pdf/namespaces/Search/classes/SearchExecution.md)
- [`Document`](../../Pdf/classes/Document.md)
- [`DocumentView`](../../UI/classes/DocumentView.md)
- [`Layer`](../../UI/classes/Layer.md)
- [`TextSelectionPlugin`](../../UI/classes/TextSelectionPlugin.md)
## Type Parameters
• **T** *extends* `Record`\ `void`\>
Interface which describes the event names and their associated callback types.
## Constructors
### new EventEmitter()
> **new EventEmitter**\<`T`\>(): [`EventEmitter`](EventEmitter.md)\<`T`\>
#### Returns
[`EventEmitter`](EventEmitter.md)\<`T`\>
## Methods
### addEventListener()
> **addEventListener**\<`K`\>(`type`, `listener`): `void`
Register a function that will be called whenever the specified event is delivered.
#### Type Parameters
• **K** *extends* `string` \| `number` \| `symbol`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event type to listen for.
• **listener**
The function that will be executed when an event of the specified type occurs.
#### Returns
`void`
***
### dispatchEvent()
> **dispatchEvent**\<`K`\>(`type`, `args`): `void`
Dispatches an event to all registered listeners.
#### Type Parameters
• **K** *extends* `string` \| `number` \| `symbol`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event type to dispatch.
• **args**: `Parameters`\<`T`\[`K`\]\>
The data associated with the event.
#### Returns
`void`
***
### removeAllListeners()
> **removeAllListeners**\<`K`\>(`type`): `void`
Remove all listeners for a given event.
#### Type Parameters
• **K** *extends* `string` \| `number` \| `symbol`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event for which to remove all listeners.
#### Returns
`void`
***
### removeEventListener()
> **removeEventListener**\<`K`\>(`type`, `listener`): `void`
Removes an event listener previously registered with addEventListener.
#### Type Parameters
• **K** *extends* `string` \| `number` \| `symbol`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event for which to remove an event listener.
• **listener**
The event listener function of the event handler to remove from the event target.
#### Returns
`void`
---
## Enumeration: LogLevel
Enum representing different log levels.
## Enumeration Members
### ALL
> **ALL**: `7`
***
### ERROR
> **ERROR**: `1`
***
### INFO
> **INFO**: `4`
***
### NONE
> **NONE**: `0`
***
### WARN
> **WARN**: `2`
---
## Function: delay()
> **delay**(`seconds`): `Promise`\<`unknown`\>
Delays execution for a specified number of seconds.
## Parameters
• **seconds**: `number`
The number of seconds to delay.
## Returns
`Promise`\<`unknown`\>
---
## Core
## Index
### Enumerations
- [LogLevel](enumerations/LogLevel.md)
### Classes
- [EventEmitter](classes/EventEmitter.md)
### Interfaces
- [Cloneable](interfaces/Cloneable.md)
- [Disposable](interfaces/Disposable.md)
### Type Aliases
- [Brand](type-aliases/Brand.md)
### Variables
- [logger](variables/logger.md)
### Functions
- [delay](functions/delay.md)
---
## Interface: Cloneable\
Represents an object that can be cloned to create a deep copy.
## Type Parameters
• **T**
The type of the object that the clone method returns.
## Methods
### clone()
> **clone**(): `T`
Creates a deep copy of the object.
#### Returns
`T`
A new instance that is a deep copy of the original object.
---
## Interface: Disposable
Disposable defines a contract for objects that require explicit
cleanup or resource release when they are no longer needed. Classes implementing
this interface should provide a `dispose` method to perform the necessary cleanup.
## Methods
### dispose()
> **dispose**(): `void`
Disposes of the object, releasing any resources it holds.
The `dispose` method is responsible for performing cleanup operations and releasing
any resources acquired by the object. Once an object is disposed, it should not
be used, and attempts to do so may result in undefined behavior.
#### Returns
`void`
---
## Type Alias: Brand\
> **Brand**\<`T`, `U`\>: `T` & `object`
Makes a branded type synonym for distinguishing between types with the same underlying structure at compile time.
For example, to distinguish between Km and miles,
at compile time, although the underlying type is the same
## Type declaration
### \[brand\]
> **\[brand\]**: `U`
## Type Parameters
• **T**
• **U**
---
## Variable: logger
> `const` **logger**: `Logger`
Singleton instance of the Logger class.
---
## Class: AnnotationManager
Class for managing annotations within a PDF document.
## Extends
- [`EventEmitter`](../../Core/classes/EventEmitter.md)\<`AnnotationManagerEventMap`\>
## Implements
- [`Disposable`](../../Core/interfaces/Disposable.md)
## Constructors
### new AnnotationManager()
> **new AnnotationManager**(`document`): [`AnnotationManager`](AnnotationManager.md)
#### Parameters
• **document**: [`Document`](Document.md)
#### Returns
[`AnnotationManager`](AnnotationManager.md)
#### Overrides
[`EventEmitter`](../../Core/classes/EventEmitter.md).[`constructor`](../../Core/classes/EventEmitter.md#constructors)
## Methods
### add()
#### add(annotation)
> **add**(`annotation`): `Promise`\<`void`\>
Adds a single annotation to the document.
##### Parameters
• **annotation**: [`Annotation`](../namespaces/Annotations/classes/Annotation.md)
The annotation to be added.
##### Returns
`Promise`\<`void`\>
#### add(annotations)
> **add**(`annotations`): `Promise`\<`void`\>
Adds multiple annotations to the document.
##### Parameters
• **annotations**: [`Annotation`](../namespaces/Annotations/classes/Annotation.md)[]
An array of annotations to be added.
##### Returns
`Promise`\<`void`\>
***
### addEventListener()
> **addEventListener**\<`K`\>(`type`, `listener`): `void`
Register a function that will be called whenever the specified event is delivered.
#### Type Parameters
• **K** *extends* keyof `AnnotationManagerEventMap`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event type to listen for.
• **listener**
The function that will be executed when an event of the specified type occurs.
#### Returns
`void`
#### Inherited from
[`EventEmitter`](../../Core/classes/EventEmitter.md).[`addEventListener`](../../Core/classes/EventEmitter.md#addeventlistener)
***
### bringToBack()
> **bringToBack**(`annotation`): `void`
**`Experimental`**
Brings the specified annotation to the back, making it appear below other annotations.
#### Parameters
• **annotation**: [`Annotation`](../namespaces/Annotations/classes/Annotation.md)
The annotation to bring to the back.
#### Returns
`void`
***
### bringToFront()
> **bringToFront**(`annotation`): `void`
**`Experimental`**
Brings the specified annotation to the front, making it appear above other annotations.
#### Parameters
• **annotation**: [`Annotation`](../namespaces/Annotations/classes/Annotation.md)
The annotation to bring to the front.
#### Returns
`void`
***
### copy()
> **copy**(`annotation`): `void`
**`Experimental`**
Creates a copy of the specified annotation.
#### Parameters
• **annotation**: [`Annotation`](../namespaces/Annotations/classes/Annotation.md)
The annotation to be copied.
#### Returns
`void`
***
### delete()
#### delete(annotation)
> **delete**(`annotation`): `Promise`\<`void`\>
Deletes a single annotation from the document.
##### Parameters
• **annotation**: [`Annotation`](../namespaces/Annotations/classes/Annotation.md)
The annotation to be deleted.
##### Returns
`Promise`\<`void`\>
#### delete(annotations)
> **delete**(`annotations`): `Promise`\<`void`\>
Deletes multiple annotations from the document.
##### Parameters
• **annotations**: [`Annotation`](../namespaces/Annotations/classes/Annotation.md)[]
An array of annotations to be deleted.
##### Returns
`Promise`\<`void`\>
#### delete(annotationId)
> **delete**(`annotationId`): `Promise`\<`void`\>
**`Experimental`**
Deletes an annotation by its ID from the document.
##### Parameters
• **annotationId**: `string`
The ID of the annotation to be deleted.
##### Returns
`Promise`\<`void`\>
***
### dispatchEvent()
> **dispatchEvent**\<`K`\>(`type`, `args`): `void`
Dispatches an event to all registered listeners.
#### Type Parameters
• **K** *extends* keyof `AnnotationManagerEventMap`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event type to dispatch.
• **args**: `Parameters`\<`AnnotationManagerEventMap`\[`K`\]\>
The data associated with the event.
#### Returns
`void`
#### Inherited from
[`EventEmitter`](../../Core/classes/EventEmitter.md).[`dispatchEvent`](../../Core/classes/EventEmitter.md#dispatchevent)
***
### dispose()
> **dispose**(): `void`
Disposes of the object, releasing any resources it holds.
The `dispose` method is responsible for performing cleanup operations and releasing
any resources acquired by the object. Once an object is disposed, it should not
be used, and attempts to do so may result in undefined behavior.
#### Returns
`void`
#### Implementation of
[`Disposable`](../../Core/interfaces/Disposable.md).[`dispose`](../../Core/interfaces/Disposable.md#dispose)
***
### getAll()
> **getAll**(): `Promise`\<[`Annotation`](../namespaces/Annotations/classes/Annotation.md)[]\>
Retrieves a list of all annotations in the document.
#### Returns
`Promise`\<[`Annotation`](../namespaces/Annotations/classes/Annotation.md)[]\>
An array containing all the annotations.
***
### getAllOnPage()
> **getAllOnPage**(`pageNumber`): `Promise`\<[`Annotation`](../namespaces/Annotations/classes/Annotation.md)[]\>
Retrieves annotations on a specific page.
#### Parameters
• **pageNumber**: `number`
The page number to retrieve annotations from.
#### Returns
`Promise`\<[`Annotation`](../namespaces/Annotations/classes/Annotation.md)[]\>
An array containing all the annotations on a specific page.
***
### getAnnotationsOnPoint()
> **getAnnotationsOnPoint**(`pageNumber`, `point`, `onlySelectable`): `Promise`\<[`Annotation`](../namespaces/Annotations/classes/Annotation.md)[]\>
Gets all annotations on a point on the page.
#### Parameters
• **pageNumber**: `number`
The page number to retrieve annotations from.
• **point**: `PdfPoint`
The PDF point on the current page.
• **onlySelectable**: `boolean`
Only return annotations which can be selected.
#### Returns
`Promise`\<[`Annotation`](../namespaces/Annotations/classes/Annotation.md)[]\>
An array containing all the annotations on point.
***
### getById()
> **getById**(`annotationId`): [`Annotation`](../namespaces/Annotations/classes/Annotation.md)
**`Experimental`**
Retrieves an annotation by its ID from the document.
#### Parameters
• **annotationId**: `string`
The ID of the annotation to retrieve.
#### Returns
[`Annotation`](../namespaces/Annotations/classes/Annotation.md)
The retrieved annotation.
***
### getTextStampAspectRatio()
> **getTextStampAspectRatio**(`text`): `Promise`\<`number`\>
Calculates the aspect ratio of a custom text stamp based on the provided text.
This method retrieves the width-to-height ratio of a text stamp, which can be used
to correctly scale the stamp when adding it to a document.
#### Parameters
• **text**: `string`
The text content of the custom text stamp for which the aspect ratio is to be calculated.
#### Returns
`Promise`\<`number`\>
A promise that resolves to the aspect ratio (width divided by height) of the custom text stamp.
***
### hide()
#### hide(annotation)
> **hide**(`annotation`): `Promise`\<`void`\>
Hides the specified annotation, making it invisible within the document.
##### Parameters
• **annotation**: [`Annotation`](../namespaces/Annotations/classes/Annotation.md)
The annotation to be hidden.
##### Returns
`Promise`\<`void`\>
#### hide(annotations)
> **hide**(`annotations`): `Promise`\<`void`\>
**`Experimental`**
Hides multiple annotations, making them invisible within the document.
##### Parameters
• **annotations**: [`Annotation`](../namespaces/Annotations/classes/Annotation.md)[]
An array of annotations to be hidden.
##### Returns
`Promise`\<`void`\>
***
### removeAllListeners()
> **removeAllListeners**\<`K`\>(`type`): `void`
Remove all listeners for a given event.
#### Type Parameters
• **K** *extends* keyof `AnnotationManagerEventMap`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event for which to remove all listeners.
#### Returns
`void`
#### Inherited from
[`EventEmitter`](../../Core/classes/EventEmitter.md).[`removeAllListeners`](../../Core/classes/EventEmitter.md#removealllisteners)
***
### removeEventListener()
> **removeEventListener**\<`K`\>(`type`, `listener`): `void`
Removes an event listener previously registered with addEventListener.
#### Type Parameters
• **K** *extends* keyof `AnnotationManagerEventMap`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event for which to remove an event listener.
• **listener**
The event listener function of the event handler to remove from the event target.
#### Returns
`void`
#### Inherited from
[`EventEmitter`](../../Core/classes/EventEmitter.md).[`removeEventListener`](../../Core/classes/EventEmitter.md#removeeventlistener)
***
### update()
#### update(annotation)
> **update**(`annotation`): `Promise`\<`void`\>
Updates a single annotation in the document.
##### Parameters
• **annotation**: [`Annotation`](../namespaces/Annotations/classes/Annotation.md)
The annotation to be updated.
##### Returns
`Promise`\<`void`\>
#### update(annotations)
> **update**(`annotations`): `Promise`\<`void`\>
Updates multiple annotations in the document.
##### Parameters
• **annotations**: [`Annotation`](../namespaces/Annotations/classes/Annotation.md)[]
An array of annotations to be updated.
##### Returns
`Promise`\<`void`\>
---
## Class: Controller
Class used for managing PDF documents.
## Extends
- [`EventEmitter`](../../Core/classes/EventEmitter.md)\<[`ControllerEventMap`](../interfaces/ControllerEventMap.md)\>
## Implements
- [`Disposable`](../../Core/interfaces/Disposable.md)
## Constructors
### new Controller()
> **new Controller**(`controllerOptions`): [`Controller`](Controller.md)
#### Parameters
• **controllerOptions**: `ControllerOptions` = `{}`
#### Returns
[`Controller`](Controller.md)
#### Overrides
[`EventEmitter`](../../Core/classes/EventEmitter.md).[`constructor`](../../Core/classes/EventEmitter.md#constructors)
## Methods
### addEventListener()
> **addEventListener**\<`K`\>(`type`, `listener`): `void`
Register a function that will be called whenever the specified event is delivered.
#### Type Parameters
• **K** *extends* `"workerErrorOcurred"`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event type to listen for.
• **listener**
The function that will be executed when an event of the specified type occurs.
#### Returns
`void`
#### Inherited from
[`EventEmitter`](../../Core/classes/EventEmitter.md).[`addEventListener`](../../Core/classes/EventEmitter.md#addeventlistener)
***
### dispatchEvent()
> **dispatchEvent**\<`K`\>(`type`, `args`): `void`
Dispatches an event to all registered listeners.
#### Type Parameters
• **K** *extends* `"workerErrorOcurred"`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event type to dispatch.
• **args**: `Parameters`\<[`ControllerEventMap`](../interfaces/ControllerEventMap.md)\[`K`\]\>
The data associated with the event.
#### Returns
`void`
#### Inherited from
[`EventEmitter`](../../Core/classes/EventEmitter.md).[`dispatchEvent`](../../Core/classes/EventEmitter.md#dispatchevent)
***
### dispose()
> **dispose**(): `void`
Disposes of the object, releasing any resources it holds.
The `dispose` method is responsible for performing cleanup operations and releasing
any resources acquired by the object. Once an object is disposed, it should not
be used, and attempts to do so may result in undefined behavior.
#### Returns
`void`
#### Implementation of
[`Disposable`](../../Core/interfaces/Disposable.md).[`dispose`](../../Core/interfaces/Disposable.md#dispose)
***
### initialize()
> **initialize**(): `Promise`\<[`Controller`](Controller.md)\>
#### Returns
`Promise`\<[`Controller`](Controller.md)\>
***
### isFeatureEnabled()
> **isFeatureEnabled**(`featureId`): `boolean`
#### Parameters
• **featureId**: [`LicensedFeatureId`](../enumerations/LicensedFeatureId.md)
#### Returns
`boolean`
***
### openDocument()
> **openDocument**(`inputDocument`): `Promise`\<[`Document`](Document.md)\>
Opens a PDF document from either a file or a remote URI.
#### Parameters
• **inputDocument**: [`InputFile`](../interfaces/InputFile.md) \| [`InputUri`](../interfaces/InputUri.md)
The input document to open.
#### Returns
`Promise`\<[`Document`](Document.md)\>
A Promise that resolves to a `Pdf.Document`.
***
### removeAllListeners()
> **removeAllListeners**\<`K`\>(`type`): `void`
Remove all listeners for a given event.
#### Type Parameters
• **K** *extends* `"workerErrorOcurred"`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event for which to remove all listeners.
#### Returns
`void`
#### Inherited from
[`EventEmitter`](../../Core/classes/EventEmitter.md).[`removeAllListeners`](../../Core/classes/EventEmitter.md#removealllisteners)
***
### removeEventListener()
> **removeEventListener**\<`K`\>(`type`, `listener`): `void`
Removes an event listener previously registered with addEventListener.
#### Type Parameters
• **K** *extends* `"workerErrorOcurred"`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event for which to remove an event listener.
• **listener**
The event listener function of the event handler to remove from the event target.
#### Returns
`void`
#### Inherited from
[`EventEmitter`](../../Core/classes/EventEmitter.md).[`removeEventListener`](../../Core/classes/EventEmitter.md#removeeventlistener)
---
## Class: Document
Represents a Pdf document.
## Extends
- [`EventEmitter`](../../Core/classes/EventEmitter.md)\<[`DocumentEventMap`](../interfaces/DocumentEventMap.md)\>
## Implements
- [`Disposable`](../../Core/interfaces/Disposable.md)
## Accessors
### annotations
> `get` **annotations**(): [`AnnotationManager`](AnnotationManager.md)
#### Returns
[`AnnotationManager`](AnnotationManager.md)
***
### controller
> `get` **controller**(): [`Controller`](Controller.md)
Gets the `Pdf.Controller`
#### Returns
[`Controller`](Controller.md)
***
### forms
> `get` **forms**(): []
#### Returns
[]
***
### hasChanges
> `get` **hasChanges**(): `boolean`
indicates if the document has been changed since the document
was opened or last saved
#### Returns
`boolean`
***
### pageCount
> `get` **pageCount**(): `number`
#### Returns
`number`
***
### pages
> `get` **pages**(): [`PageList`](PageList.md)
#### Returns
[`PageList`](PageList.md)
## Methods
### addEventListener()
> **addEventListener**\<`K`\>(`type`, `listener`): `void`
Register a function that will be called whenever the specified event is delivered.
#### Type Parameters
• **K** *extends* `never`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event type to listen for.
• **listener**
The function that will be executed when an event of the specified type occurs.
#### Returns
`void`
#### Inherited from
[`EventEmitter`](../../Core/classes/EventEmitter.md).[`addEventListener`](../../Core/classes/EventEmitter.md#addeventlistener)
***
### dispatchEvent()
> **dispatchEvent**\<`K`\>(`type`, `args`): `void`
Dispatches an event to all registered listeners.
#### Type Parameters
• **K** *extends* `never`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event type to dispatch.
• **args**: `Parameters`\<[`DocumentEventMap`](../interfaces/DocumentEventMap.md)\[`K`\]\>
The data associated with the event.
#### Returns
`void`
#### Inherited from
[`EventEmitter`](../../Core/classes/EventEmitter.md).[`dispatchEvent`](../../Core/classes/EventEmitter.md#dispatchevent)
***
### dispose()
> **dispose**(): `void`
Disposes of the object, releasing any resources it holds.
The `dispose` method is responsible for performing cleanup operations and releasing
any resources acquired by the object. Once an object is disposed, it should not
be used, and attempts to do so may result in undefined behavior.
#### Returns
`void`
#### Implementation of
[`Disposable`](../../Core/interfaces/Disposable.md).[`dispose`](../../Core/interfaces/Disposable.md#dispose)
***
### getMetadata()
> **getMetadata**(): `Promise`\<[`Metadata`](Metadata.md)\>
#### Returns
`Promise`\<[`Metadata`](Metadata.md)\>
***
### loadOutlines()
> **loadOutlines**(): `Promise`\<`OutlineItem`[]\>
Loads outlines of a `Pdf.Document`.
#### Returns
`Promise`\<`OutlineItem`[]\>
A Promise that resolves to an Array containing the outlines.
***
### loadTextFragments()
> **loadTextFragments**(): `Promise`\<[`TextFragment`](../interfaces/TextFragment.md)[]\>
Loads text fragments of a `Pdf.Document`.
#### Returns
`Promise`\<[`TextFragment`](../interfaces/TextFragment.md)[]\>
A Promise that resolves to an Array containing the text fragments.
***
### registerImage()
> **registerImage**(`image`): `Promise`\<[`PdfImage`](../interfaces/PdfImage.md)\>
Register the image in the PDF document so it can be reused.
#### Parameters
• **image**: `Uint8Array`
I
#### Returns
`Promise`\<[`PdfImage`](../interfaces/PdfImage.md)\>
***
### registerPdfContent()
> **registerPdfContent**(`page`): `Promise`\<[`PdfContent`](../namespaces/Drawing/interfaces/PdfContent.md)\>
Register the PDF page in the PDF document so it can be reused.
#### Parameters
• **page**: [`Page`](Page.md)
#### Returns
`Promise`\<[`PdfContent`](../namespaces/Drawing/interfaces/PdfContent.md)\>
***
### removeAllListeners()
> **removeAllListeners**\<`K`\>(`type`): `void`
Remove all listeners for a given event.
#### Type Parameters
• **K** *extends* `never`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event for which to remove all listeners.
#### Returns
`void`
#### Inherited from
[`EventEmitter`](../../Core/classes/EventEmitter.md).[`removeAllListeners`](../../Core/classes/EventEmitter.md#removealllisteners)
***
### removeEventListener()
> **removeEventListener**\<`K`\>(`type`, `listener`): `void`
Removes an event listener previously registered with addEventListener.
#### Type Parameters
• **K** *extends* `never`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event for which to remove an event listener.
• **listener**
The event listener function of the event handler to remove from the event target.
#### Returns
`void`
#### Inherited from
[`EventEmitter`](../../Core/classes/EventEmitter.md).[`removeEventListener`](../../Core/classes/EventEmitter.md#removeeventlistener)
***
### renderPage()
> **renderPage**(`pageNumber`, `width`, `height`): `Promise`\<[`Image`](../../UI/interfaces/Image.md)\>
#### Parameters
• **pageNumber**: `number`
• **width**: `number`
• **height**: `number`
#### Returns
`Promise`\<[`Image`](../../UI/interfaces/Image.md)\>
***
### save()
> **save**(`options`): `Promise`\<`Blob`\>
Saves the changes made to the `Pdf.Document`.
#### Parameters
• **options**: [`DocumentSaveOptions`](../interfaces/DocumentSaveOptions.md) = `defaultDocumentSaveOptions`
Options for configuring the document save behavior.
#### Returns
`Promise`\<`Blob`\>
A Promise that resolves to a Blob containing the updated PDF document.
---
## Class: FileNotFoundError
## Extends
- `Error`
## Constructors
### new FileNotFoundError()
> **new FileNotFoundError**(`message`?): [`FileNotFoundError`](FileNotFoundError.md)
#### Parameters
• **message?**: `string`
#### Returns
[`FileNotFoundError`](FileNotFoundError.md)
#### Inherited from
`Error.constructor`
### new FileNotFoundError()
> **new FileNotFoundError**(`message`?, `options`?): [`FileNotFoundError`](FileNotFoundError.md)
#### Parameters
• **message?**: `string`
• **options?**: `ErrorOptions`
#### Returns
[`FileNotFoundError`](FileNotFoundError.md)
#### Inherited from
`Error.constructor`
## Properties
### cause?
> `optional` **cause**: `unknown`
#### Inherited from
`Error.cause`
***
### message
> **message**: `string`
#### Inherited from
`Error.message`
***
### name
> **name**: `string` = `'FileNotFoundError'`
#### Overrides
`Error.name`
***
### stack?
> `optional` **stack**: `string`
#### Inherited from
`Error.stack`
---
## Class: InvalidPasswordError
## Extends
- `Error`
## Constructors
### new InvalidPasswordError()
> **new InvalidPasswordError**(`message`?): [`InvalidPasswordError`](InvalidPasswordError.md)
#### Parameters
• **message?**: `string`
#### Returns
[`InvalidPasswordError`](InvalidPasswordError.md)
#### Inherited from
`Error.constructor`
### new InvalidPasswordError()
> **new InvalidPasswordError**(`message`?, `options`?): [`InvalidPasswordError`](InvalidPasswordError.md)
#### Parameters
• **message?**: `string`
• **options?**: `ErrorOptions`
#### Returns
[`InvalidPasswordError`](InvalidPasswordError.md)
#### Inherited from
`Error.constructor`
## Properties
### cause?
> `optional` **cause**: `unknown`
#### Inherited from
`Error.cause`
***
### message
> **message**: `string`
#### Inherited from
`Error.message`
***
### name
> **name**: `string` = `'InvalidPasswordError'`
#### Overrides
`Error.name`
***
### stack?
> `optional` **stack**: `string`
#### Inherited from
`Error.stack`
---
## Class: Metadata
Document metadata according to the PDF standard (PDF 1.7)
## Constructors
### new Metadata()
> **new Metadata**(): [`Metadata`](Metadata.md)
#### Returns
[`Metadata`](Metadata.md)
## Properties
### author
> **author**: `string`
The name of the person who created the document.
***
### creationDate
> **creationDate**: `Date`
The date and time the document was created.
***
### creator
> **creator**: `string`
If the document was converted to PDF from another format, the name of the
application that created the original document from which it was converted.
***
### keywords
> **keywords**: `string`
Keywords associated with the document.
***
### modificationDate
> **modificationDate**: `Date`
The date and time the document was most recently modified.
***
### producer
> **producer**: `string`
If the document was converted to PDF from another format, the name of the
application that converted it to PDF.
***
### subject
> **subject**: `string`
The subject of the document.
***
### title
> **title**: `string`
The document's title.
---
## Class: NotLoadedError
## Extends
- `Error`
## Constructors
### new NotLoadedError()
> **new NotLoadedError**(`message`?): [`NotLoadedError`](NotLoadedError.md)
#### Parameters
• **message?**: `string`
#### Returns
[`NotLoadedError`](NotLoadedError.md)
#### Inherited from
`Error.constructor`
### new NotLoadedError()
> **new NotLoadedError**(`message`?, `options`?): [`NotLoadedError`](NotLoadedError.md)
#### Parameters
• **message?**: `string`
• **options?**: `ErrorOptions`
#### Returns
[`NotLoadedError`](NotLoadedError.md)
#### Inherited from
`Error.constructor`
## Properties
### cause?
> `optional` **cause**: `unknown`
#### Inherited from
`Error.cause`
***
### message
> **message**: `string`
#### Inherited from
`Error.message`
***
### name
> **name**: `string` = `'NotLoadedError'`
#### Overrides
`Error.name`
***
### stack?
> `optional` **stack**: `string`
#### Inherited from
`Error.stack`
---
## Class: Page
A single page in a Pdf document.
## Extends
- [`EventEmitter`](../../Core/classes/EventEmitter.md)\<[`PageEventMap`](../interfaces/PageEventMap.md)\>
## Implements
- [`Disposable`](../../Core/interfaces/Disposable.md)
## Accessors
### document
> `get` **document**(): [`Document`](Document.md)
the pdf document to which the page belongs
#### Returns
[`Document`](Document.md)
***
### hasChanges
> `get` **hasChanges**(): `boolean`
indicates if the page or its content has been changed since the document
was last saved
#### Returns
`boolean`
***
### height
> `get` **height**(): `number`
Height of the page in PDF coordinates.
This represents the height of the page, taking into account the rotation.
#### Returns
`number`
***
### isDeleted
> `get` **isDeleted**(): `boolean`
indicates whether the page was deleted
#### Returns
`boolean`
***
### originalHeight
> `get` **originalHeight**(): `number`
Original height of the page in PDF coordinates.
This represents the original height of the page without considering any rotation.
#### Returns
`number`
***
### originalWidth
> `get` **originalWidth**(): `number`
Original width of the page in PDF coordinates.
This represents the original width of the page without considering any rotation.
#### Returns
`number`
***
### pageNumber
> `get` **pageNumber**(): `number`
page number
#### Returns
`number`
***
### rotation
> `get` **rotation**(): [`Rotation`](../enumerations/Rotation.md)
Rotation of the page
#### Returns
[`Rotation`](../enumerations/Rotation.md)
***
### width
> `get` **width**(): `number`
Width of the page in PDF coordinates.
This represents the width of the page, taking into account the rotation.
#### Returns
`number`
## Methods
### addEventListener()
> **addEventListener**\<`K`\>(`type`, `listener`): `void`
Register a function that will be called whenever the specified event is delivered.
#### Type Parameters
• **K** *extends* `"textFragmentsLoaded"`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event type to listen for.
• **listener**
The function that will be executed when an event of the specified type occurs.
#### Returns
`void`
#### Inherited from
[`EventEmitter`](../../Core/classes/EventEmitter.md).[`addEventListener`](../../Core/classes/EventEmitter.md#addeventlistener)
***
### dispatchEvent()
> **dispatchEvent**\<`K`\>(`type`, `args`): `void`
Dispatches an event to all registered listeners.
#### Type Parameters
• **K** *extends* `"textFragmentsLoaded"`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event type to dispatch.
• **args**: `Parameters`\<[`PageEventMap`](../interfaces/PageEventMap.md)\[`K`\]\>
The data associated with the event.
#### Returns
`void`
#### Inherited from
[`EventEmitter`](../../Core/classes/EventEmitter.md).[`dispatchEvent`](../../Core/classes/EventEmitter.md#dispatchevent)
***
### dispose()
> **dispose**(): `void`
Disposes of the object, releasing any resources it holds.
The `dispose` method is responsible for performing cleanup operations and releasing
any resources acquired by the object. Once an object is disposed, it should not
be used, and attempts to do so may result in undefined behavior.
#### Returns
`void`
#### Implementation of
[`Disposable`](../../Core/interfaces/Disposable.md).[`dispose`](../../Core/interfaces/Disposable.md#dispose)
***
### getTextFragments()
> **getTextFragments**(): [`TextFragment`](../interfaces/TextFragment.md)[]
Gets text fragments of a `Pdf.Page`.
#### Returns
[`TextFragment`](../interfaces/TextFragment.md)[]
A Promise that resolves to an Array containing the text fragments.
#### Throws
`Pdf.NotLoadedError` if text fragments are not loaded yet.
***
### loadTextFragments()
> **loadTextFragments**(): `Promise`\<[`TextFragment`](../interfaces/TextFragment.md)[]\>
Loads text fragments of a `Pdf.Page`.
#### Returns
`Promise`\<[`TextFragment`](../interfaces/TextFragment.md)[]\>
A Promise that resolves to an Array containing the text fragments.
***
### removeAllListeners()
> **removeAllListeners**\<`K`\>(`type`): `void`
Remove all listeners for a given event.
#### Type Parameters
• **K** *extends* `"textFragmentsLoaded"`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event for which to remove all listeners.
#### Returns
`void`
#### Inherited from
[`EventEmitter`](../../Core/classes/EventEmitter.md).[`removeAllListeners`](../../Core/classes/EventEmitter.md#removealllisteners)
***
### removeEventListener()
> **removeEventListener**\<`K`\>(`type`, `listener`): `void`
Removes an event listener previously registered with addEventListener.
#### Type Parameters
• **K** *extends* `"textFragmentsLoaded"`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event for which to remove an event listener.
• **listener**
The event listener function of the event handler to remove from the event target.
#### Returns
`void`
#### Inherited from
[`EventEmitter`](../../Core/classes/EventEmitter.md).[`removeEventListener`](../../Core/classes/EventEmitter.md#removeeventlistener)
***
### render()
> **render**(`renderOptions`): `Promise`\<`Blob`\>
Render the given page
#### Parameters
• **renderOptions**: [`PageRenderOptions`](PageRenderOptions.md)
#### Returns
`Promise`\<`Blob`\>
Blob containing the image data
***
### rotate()
> **rotate**(`direction`, `degree`): `void`
Rotates the page in the specified direction by the specified degree
The rotation can only be done in steps of 90 degrees or a multiple thereof
#### Parameters
• **direction**: [`RotationDirection`](../enumerations/RotationDirection.md)
clockwise or counter-clockwise
• **degree**: `number` = `90`
rotation in degrees in multiples of 90
#### Returns
`void`
***
### transformDocumentViewPointQuadrilateralToPdfPointQuadrilateral()
> **transformDocumentViewPointQuadrilateralToPdfPointQuadrilateral**(`quadrilateral`, `width`, `height`, `rotation`): [`Quadrilateral`](../namespaces/Geometry/classes/Quadrilateral.md)\<`PdfPoint`\>
Converts a quadrilateral from document view coordinates to PDF coordinates.
This function transforms a `Quadrilateral`, which corresponds to a quadrilateral scaled proportionally based on the rendered size of the page on screen,
to a `Quadrilateral`, which is measured in PDF units. The conversion takes into account the dimensions of the document view page canvas and the rotation of the page.
#### Parameters
• **quadrilateral**: [`Quadrilateral`](../namespaces/Geometry/classes/Quadrilateral.md)\<`DocumentViewPoint`\>
The `Quadrilateral` object representing the quadrilateral in document view coordinates.
• **width**: `number`
The width of the document view page canvas.
• **height**: `number`
The height of the document view page canvas.
• **rotation**: [`Rotation`](../enumerations/Rotation.md)
The rotation of the page.
#### Returns
[`Quadrilateral`](../namespaces/Geometry/classes/Quadrilateral.md)\<`PdfPoint`\>
A new instance of `Quadrilateral` representing the converted coordinates in PDF units.
***
### transformDocumentViewPointRectangleToPdfPointRectangle()
> **transformDocumentViewPointRectangleToPdfPointRectangle**(`rectangle`, `width`, `height`, `rotation`): [`Rectangle`](../namespaces/Geometry/classes/Rectangle.md)\<`PdfPoint`\>
Converts a rectangle from document view coordinates to PDF coordinates.
This function transforms a `Rectangle`, which corresponds to a rectangle scaled proportionally based on the rendered size of the page on screen,
to a `Rectangle`, which is measured in PDF units. The conversion takes into account the dimensions of the document view page canvas and the rotation of the page.
#### Parameters
• **rectangle**: [`Rectangle`](../namespaces/Geometry/classes/Rectangle.md)\<`DocumentViewPoint`\>
The `Rectangle` object representing the rectangle in document view coordinates.
• **width**: `number`
The width of the document view page canvas.
• **height**: `number`
The height of the document view page canvas.
• **rotation**: [`Rotation`](../enumerations/Rotation.md)
The rotation of the page.
#### Returns
[`Rectangle`](../namespaces/Geometry/classes/Rectangle.md)\<`PdfPoint`\>
A new instance of `Rectangle` representing the converted coordinates in PDF units.
***
### transformDocumentViewPointToPdfPoint()
> **transformDocumentViewPointToPdfPoint**(`point`, `width`, `height`, `rotation`): `PdfPoint`
Converts a point from document view coordinates to PDF coordinates.
This function transforms a `DocumentViewPoint`, which corresponds to a PDF point scaled proportionally based on the rendered size of the page on screen,
to a `PdfPoint`, which is measured in PDF units. The conversion takes into account the dimensions of the document view page canvas and the rotation of the page.
#### Parameters
• **point**: `DocumentViewPoint`
The `DocumentViewPoint` object representing the point in document view coordinates.
• **width**: `number`
The width of the document view page canvas.
• **height**: `number`
The height of the document view page canvas.
• **rotation**: [`Rotation`](../enumerations/Rotation.md)
The rotation of the page.
#### Returns
`PdfPoint`
A new instance of `PdfPoint` representing the converted coordinates in PDF units.
***
### transformPdfPointQuadrilateralToDocumentViewPointQuadrilateral()
> **transformPdfPointQuadrilateralToDocumentViewPointQuadrilateral**(`quadrilateral`, `width`, `height`, `rotation`): [`Quadrilateral`](../namespaces/Geometry/classes/Quadrilateral.md)\<`DocumentViewPoint`\>
Converts a quadrilateral from PDF coordinates to document view coordinates.
This function transforms a `Quadrilateral`, which is measured in PDF units, to a `Quadrilateral`,
which corresponds to a quadrilateral scaled proportionally based on the rendered size of the page on screen.
The conversion takes into account the dimensions of the document view page canvas and the rotation of the page.
#### Parameters
• **quadrilateral**: [`Quadrilateral`](../namespaces/Geometry/classes/Quadrilateral.md)\<`PdfPoint`\>
The `Quadrilateral` object representing the quadrilateral in PDF coordinates.
• **width**: `number`
The width of the document view page canvas.
• **height**: `number`
The height of the document view page canvas.
• **rotation**: [`Rotation`](../enumerations/Rotation.md)
The rotation of the page.
#### Returns
[`Quadrilateral`](../namespaces/Geometry/classes/Quadrilateral.md)\<`DocumentViewPoint`\>
A new instance of `Quadrilateral` representing the converted coordinates in document view units.
***
### transformPdfPointRectangleToDocumentViewPointRectangle()
> **transformPdfPointRectangleToDocumentViewPointRectangle**(`rectangle`, `width`, `height`, `rotation`): [`Rectangle`](../namespaces/Geometry/classes/Rectangle.md)\<`DocumentViewPoint`\>
Converts a rectangle from PDF coordinates to document view coordinates.
This function transforms a `Rectangle`, which is measured in PDF units, to a `Rectangle`,
which corresponds to a rectangle scaled proportionally based on the rendered size of the page on screen.
The conversion takes into account the dimensions of the document view page canvas and the rotation of the page.
#### Parameters
• **rectangle**: [`Rectangle`](../namespaces/Geometry/classes/Rectangle.md)\<`PdfPoint`\>
The `Rectangle` object representing the rectangle in PDF coordinates.
• **width**: `number`
The width of the document view page canvas.
• **height**: `number`
The height of the document view page canvas.
• **rotation**: [`Rotation`](../enumerations/Rotation.md)
The rotation of the page.
#### Returns
[`Rectangle`](../namespaces/Geometry/classes/Rectangle.md)\<`DocumentViewPoint`\>
A new instance of `Rectangle` representing the converted coordinates in document view units.
***
### transformPdfPointToDocumentViewPoint()
> **transformPdfPointToDocumentViewPoint**(`point`, `width`, `height`, `rotation`): `DocumentViewPoint`
Converts a point from PDF coordinates to document view coordinates.
This function transforms a `PdfPoint`, which is measured in PDF units, to a `DocumentViewPoint`,
which corresponds to a PDF point scaled proportionally based on the rendered size of the page on screen.
The conversion takes into account the dimensions of the document view page canvas and the rotation of the page.
#### Parameters
• **point**: `PdfPoint`
The `PdfPoint` object representing the point in PDF coordinates.
• **width**: `number`
The width of the document view page canvas.
• **height**: `number`
The height of the document view page canvas.
• **rotation**: [`Rotation`](../enumerations/Rotation.md)
The rotation of the page.
#### Returns
`DocumentViewPoint`
A new instance of `DocumentViewPoint` representing the converted coordinates in document view units.
***
### calculateRotatedDocumentViewPoint()
> `static` **calculateRotatedDocumentViewPoint**(`point`, `rotation`, `pageWidth`, `pageHeight`): `DocumentViewPoint`
Calculates rotated document view point around page center.
#### Parameters
• **point**: `DocumentViewPoint`
The `DocumentViewPoint` object representing point to be rotated around page center.
• **rotation**: [`Rotation`](../enumerations/Rotation.md)
The rotation value to apply to a point.
• **pageWidth**: `number`
• **pageHeight**: `number`
#### Returns
`DocumentViewPoint`
A new instance of `DocumentViewPoint` representing the rotated point around page center.
***
### calculateRotatedPdfPoint()
> `static` **calculateRotatedPdfPoint**(`point`, `rotation`, `pageWidth`, `pageHeight`): `PdfPoint`
Calculates rotated PDF point around center page center.
#### Parameters
• **point**: `PdfPoint`
The `PdfPoint` object representing point to be rotated around page center.
• **rotation**: [`Rotation`](../enumerations/Rotation.md)
The rotation value to apply to a point.
• **pageWidth**: `number`
• **pageHeight**: `number`
#### Returns
`PdfPoint`
A new instance of `PdfPoint` representing the rotated point around page center.
---
## Class: PageList
Class for all page-related operations in a PDF document.
## Implements
- [`Disposable`](../../Core/interfaces/Disposable.md)
## Methods
### add()
#### add(page, index)
> **add**(`page`, `index`?): `Promise`\<`void`\>
**`Experimental`**
Adds a page to the document.
##### Parameters
• **page**: [`Page`](Page.md)
Page to be added.
• **index?**: `number`
Page index on which page will be added to the document.
If not provided, the default is to add the page at the end of the document.
##### Returns
`Promise`\<`void`\>
#### add(pages, index)
> **add**(`pages`, `index`?): `Promise`\<`void`\>
**`Experimental`**
Adds multiple pages to the document.
##### Parameters
• **pages**: [`Page`](Page.md)[]
Pages to be added.
• **index?**: `number`
Page index on which first page in the array will be added.
Other pages will be added consecutively after the first one.
If not provided, the default is to add the pages at the end of the document.
##### Returns
`Promise`\<`void`\>
***
### delete()
#### delete(page)
> **delete**(`page`): `Promise`\<`void`\>
**`Experimental`**
Deletes a single page from the document.
##### Parameters
• **page**: [`Page`](Page.md)
##### Returns
`Promise`\<`void`\>
#### delete(pages)
> **delete**(`pages`): `Promise`\<`void`\>
**`Experimental`**
Deletes multiple pages from the document.
##### Parameters
• **pages**: [`Page`](Page.md)[]
##### Returns
`Promise`\<`void`\>
***
### dispose()
> **dispose**(): `void`
Disposes of the object, releasing any resources it holds.
The `dispose` method is responsible for performing cleanup operations and releasing
any resources acquired by the object. Once an object is disposed, it should not
be used, and attempts to do so may result in undefined behavior.
#### Returns
`void`
#### Implementation of
[`Disposable`](../../Core/interfaces/Disposable.md).[`dispose`](../../Core/interfaces/Disposable.md#dispose)
***
### getAll()
> **getAll**(): [`Page`](Page.md)[]
Get an array with all pages in the document.
#### Returns
[`Page`](Page.md)[]
An array of Page objects representing all pages in the document.
***
### getByIndex()
> **getByIndex**(`pageIndex`): [`Page`](Page.md)
Get a page by index.
#### Parameters
• **pageIndex**: `number`
The index of the page to retrieve.
#### Returns
[`Page`](Page.md)
The Page object at the specified index.
***
### getByNumber()
> **getByNumber**(`pageNumber`): [`Page`](Page.md)
Get a page by its page number.
#### Parameters
• **pageNumber**: `number`
The page number to search for.
#### Returns
[`Page`](Page.md)
The Page object with the specified page number, or undefined if not found.
***
### rotate()
#### rotate(page, options)
> **rotate**(`page`, `options`?): `Promise`\<`void`\>
**`Experimental`**
Rotates a single page.
##### Parameters
• **page**: [`Page`](Page.md)
Page to be rotated.
• **options?**
Optional parameters for specifying the rotation angle.
• **options.absoluteRotation?**: `number`
• **options.rotation?**: `number`
##### Returns
`Promise`\<`void`\>
#### rotate(pages, options)
> **rotate**(`pages`, `options`?): `Promise`\<`void`\>
**`Experimental`**
Rotates multiple pages.
##### Parameters
• **pages**: [`Page`](Page.md)[]
An array of pages to be rotated.
• **options?**
Optional parameters for specifying the rotation angle.
• **options.absoluteRotation?**: `number`
• **options.rotation?**: `number`
##### Returns
`Promise`\<`void`\>
---
## Class: PageRenderOptions
**`Experimental`**
## Constructors
### new PageRenderOptions()
> **new PageRenderOptions**(): [`PageRenderOptions`](PageRenderOptions.md)
**`Experimental`**
#### Returns
[`PageRenderOptions`](PageRenderOptions.md)
## Properties
### noPrint
> **noPrint**: `boolean`
**`Experimental`**
## Accessors
### annotationFilter
> `set` **annotationFilter**(`filter`): `void`
**`Experimental`**
#### Parameters
• **filter**
---
## Enumeration: DestinationType
Supported PDF destination types
## Enumeration Members
### Direct
> **Direct**: `1`
A destination that directly points to a specific location in the document.
***
### FitHeight
> **FitHeight**: `6`
A destination fits the height of a page into the viewport.
***
### FitPage
> **FitPage**: `4`
A destination fits an entire page into the viewport.
***
### FitRectangle
> **FitRectangle**: `0`
A destination that fits a specified area of a page into the viewport.
***
### FitWidth
> **FitWidth**: `5`
A destination fits the width of a page into the viewport.
***
### LocationZoom
> **LocationZoom**: `2`
A destination that points to a specific location on the target page, using a specified zoom factor.
The location is displayed in the top left corner of the viewport (if possible).
***
### Named
> **Named**: `3`
A destination that can be referred by name.
---
## Enumeration: FitMode(Enumerations)
Setting how the viewport will be fitted to the visible content
## Enumeration Members
### FitPage
> **FitPage**: `2`
Fit viewport to be able to show largest visible page in its entirety
***
### FitWidth
> **FitWidth**: `1`
Fit viewport to width of widest visible page
***
### None
> **None**: `0`
Do not fit
---
## Enumeration: LicensedFeatureId
Enum representing a unique identifier for each PDF Web SDK licensed feature.
Each feature is represented by a bit flag, allowing multiple features to be combined using bitwise operations.
## Enumeration Members
### AnnotationAdding
> **AnnotationAdding**: `2`
Adding annotations to a document.
Grants users the ability to create new annotations.
***
### AnnotationDeleting
> **AnnotationDeleting**: `8`
Deleting annotations from a document.
Enables users to remove existing annotations permanently.
***
### AnnotationHistory
> **AnnotationHistory**: `16`
Viewing and interacting with an annotation's history.
Provides access to the historical changes and revisions made to annotations.
***
### AnnotationReading
> **AnnotationReading**: `1`
Reading and inspecting annotations in a document.
Enables users to fetch existing annotations without making modifications.
***
### AnnotationUpdating
> **AnnotationUpdating**: `4`
Updating existing annotations in a document.
Allows users to modify properties or contents of previously created annotations.
***
### AutomatedTextProcessing
> **AutomatedTextProcessing**: `64`
Automated text processing capabilities.
Enables the retrieval of text content within the document, including its position, bounding box, and glyph offsets.
***
### DocumentMerging
> **DocumentMerging**: `1024`
Merging multiple PDF documents into a single file.
Provides functionality to combine pages and content from separate documents.
***
### FormFieldFilling
> **FormFieldFilling**: `32`
Filling form fields in a document.
Enables users to fill out or edit form fields such as text boxes, checkboxes, and dropdowns.
***
### PageAdding
> **PageAdding**: `128`
Adding blank pages to the document.
Grants users the ability to insert new, empty pages at specific positions within the document.
***
### PageDeleting
> **PageDeleting**: `256`
Deleting pages from the document.
Allows users to remove existing pages from a document.
***
### PageRotation
> **PageRotation**: `512`
Rotating pages within the document.
Enables users to change the orientation of pages (e.g., 90°, 180° rotation).
***
### Redaction
> **Redaction**: `2048`
Redacting sensitive information from the document.
Allows users to permanently remove confidential content.
---
## Enumeration: PageLayoutMode(Enumerations)
Setting how the pages will be arranged on the viewport.
According to the PDF standard (PDF 1.7)
## Enumeration Members
### OneColumn
> **OneColumn**: `1`
Display the pages in one column.
***
### SinglePage
> **SinglePage**: `0`
Display one page at a time .
***
### TwoColumnLeft
> **TwoColumnLeft**: `2`
Display the pages in two columns, with odd-numbered pages on the left.
***
### TwoColumnRight
> **TwoColumnRight**: `3`
Display the pages in two columns, with odd-numbered pages on the right.
***
### TwoPageLeft
> **TwoPageLeft**: `4`
Display two pages at a time, with odd-numbered pages on the left.
***
### TwoPageRight
> **TwoPageRight**: `5`
Display two pages at a time, with odd-numbered pages on the right.
---
## Enumeration: Rotation(Enumerations)
Enumerates different rotation values in 90 degree steps.
## Enumeration Members
### Clockwise
> **Clockwise**: `90`
Represents 90 degree clockwise rotation.
***
### CounterClockwise
> **CounterClockwise**: `270`
Represents 270 degree counter-clockwise rotation.
***
### None
> **None**: `0`
Represents 0 degree rotation (no rotation).
***
### UpsideDown
> **UpsideDown**: `180`
Represents 180 degree rotation (upside down).
---
## Enumeration: RotationDirection
## Enumeration Members
### clockwise
> **clockwise**: `0`
***
### counterClockwise
> **counterClockwise**: `1`
---
## Pdf
## Index
### Namespaces
- [Actions](namespaces/Actions/index.md)
- [Annotations](namespaces/Annotations/index.md)
- [Drawing](namespaces/Drawing/index.md)
- [Forms](namespaces/Forms/index.md)
- [Geometry](namespaces/Geometry/index.md)
- [Search](namespaces/Search/index.md)
### Enumerations
- [DestinationType](enumerations/DestinationType.md)
- [FitMode](enumerations/FitMode.md)
- [LicensedFeatureId](enumerations/LicensedFeatureId.md)
- [PageLayoutMode](enumerations/PageLayoutMode.md)
- [Rotation](enumerations/Rotation.md)
- [RotationDirection](enumerations/RotationDirection.md)
### Classes
- [AnnotationManager](classes/AnnotationManager.md)
- [Controller](classes/Controller.md)
- [Document](classes/Document.md)
- [FileNotFoundError](classes/FileNotFoundError.md)
- [InvalidPasswordError](classes/InvalidPasswordError.md)
- [Metadata](classes/Metadata.md)
- [NotLoadedError](classes/NotLoadedError.md)
- [Page](classes/Page.md)
- [PageList](classes/PageList.md)
- [PageRenderOptions](classes/PageRenderOptions.md)
### Interfaces
- [ControllerEventMap](interfaces/ControllerEventMap.md)
- [Destination](interfaces/Destination.md)
- [DocumentEventMap](interfaces/DocumentEventMap.md)
- [DocumentSaveOptions](interfaces/DocumentSaveOptions.md)
- [HttpOptions](interfaces/HttpOptions.md)
- [InputDocument](interfaces/InputDocument.md)
- [InputFile](interfaces/InputFile.md)
- [InputUri](interfaces/InputUri.md)
- [PageEventMap](interfaces/PageEventMap.md)
- [PdfImage](interfaces/PdfImage.md)
- [SaveOptions](interfaces/SaveOptions.md)
- [TextFragment](interfaces/TextFragment.md)
---
## Interface: ControllerEventMap
Interface defining event types for `Pdf.Controller`.
## Properties
### workerErrorOcurred()
> **workerErrorOcurred**: (`error`) => `void`
Event triggered when a worker task fails
The event payload is an `Error`
#### Parameters
• **error**: `Error`
#### Returns
`void`
---
## Interface: Destination
## Properties
### bottom?
> `optional` **bottom**: `number`
***
### centering?
> `optional` **centering**: `boolean`
***
### destinationType
> **destinationType**: [`DestinationType`](../enumerations/DestinationType.md)
***
### fitContent?
> `optional` **fitContent**: `boolean`
***
### left?
> `optional` **left**: `number`
***
### pageNumber
> **pageNumber**: `number`
***
### rectangle?
> `optional` **rectangle**: [`Rectangle`](../namespaces/Geometry/classes/Rectangle.md)\<`PdfPoint`\>
***
### right?
> `optional` **right**: `number`
***
### top?
> `optional` **top**: `number`
***
### zoom?
> `optional` **zoom**: `number`
---
## Interface: DocumentEventMap
Interface defining event types for `Pdf.Document`.
---
## Interface: DocumentSaveOptions(Interfaces)
Options for configuring the document save behavior.
## Properties
### saveOriginal?
> `optional` **saveOriginal**: `boolean`
Indicates whether to save the original input document, discarding any interactive changes.
When set to true, it bypasses the regular save process, avoiding any automatic repairs or modifications.
#### Default Value
`false`
---
## Interface: HttpOptions
Options that are applied to an HTTP request.
## Properties
### headers?
> `optional` **headers**: `object`
A set of custom HTTP headers to include in the request.
Each header is represented as a key-value pair, where the key is the header name
and the value is the header value. These headers will be sent with the HTTP request
when loading a document from a URI.
#### Index Signature
\[`key`: `string`\]: `string`
---
## Interface: InputDocument
## Extended by
- [`InputFile`](InputFile.md)
- [`InputUri`](InputUri.md)
## Properties
### annotationTag?
> `optional` **annotationTag**: `string`
Tag that helps grouping annotations coming from present document (PDF, FDF or XFDF).
***
### autoRepairDisabled?
> `optional` **autoRepairDisabled**: `boolean`
A boolean property that controls whether automatic repairs on PDF files are disabled.
Setting this property to `true` prevents the application from performing any automatic
repair operations on PDF files, which could alter the file's structure and potentially
invalidate digital signatures within the document.
#### Default Value
`false`
***
### fileName?
> `optional` **fileName**: `string`
Name for the input document
***
### password?
> `optional` **password**: `string`
The password used for opening the PdfDocument.
---
## Interface: InputFile(Interfaces)
A file that can be opened on a `Blob`, `File` or `Uint8Array`.
## Extends
- [`InputDocument`](InputDocument.md)
## Properties
### annotationTag?
> `optional` **annotationTag**: `string`
Tag that helps grouping annotations coming from present document (PDF, FDF or XFDF).
#### Inherited from
[`InputDocument`](InputDocument.md).[`annotationTag`](InputDocument.md#annotationtag)
***
### autoRepairDisabled?
> `optional` **autoRepairDisabled**: `boolean`
A boolean property that controls whether automatic repairs on PDF files are disabled.
Setting this property to `true` prevents the application from performing any automatic
repair operations on PDF files, which could alter the file's structure and potentially
invalidate digital signatures within the document.
#### Default Value
`false`
#### Inherited from
[`InputDocument`](InputDocument.md).[`autoRepairDisabled`](InputDocument.md#autorepairdisabled)
***
### data
> **data**: `Uint8Array` \| `Blob` \| `File`
A `Blob`, `File` or `Uint8Array` containing the file.
***
### fileName?
> `optional` **fileName**: `string`
Name for the input document
#### Inherited from
[`InputDocument`](InputDocument.md).[`fileName`](InputDocument.md#filename)
***
### password?
> `optional` **password**: `string`
The password used for opening the PdfDocument.
#### Inherited from
[`InputDocument`](InputDocument.md).[`password`](InputDocument.md#password)
---
## Interface: InputUri(Interfaces)
A file that can be opened on a text-uri.
## Extends
- [`InputDocument`](InputDocument.md)
## Properties
### annotationTag?
> `optional` **annotationTag**: `string`
Tag that helps grouping annotations coming from present document (PDF, FDF or XFDF).
#### Inherited from
[`InputDocument`](InputDocument.md).[`annotationTag`](InputDocument.md#annotationtag)
***
### autoRepairDisabled?
> `optional` **autoRepairDisabled**: `boolean`
A boolean property that controls whether automatic repairs on PDF files are disabled.
Setting this property to `true` prevents the application from performing any automatic
repair operations on PDF files, which could alter the file's structure and potentially
invalidate digital signatures within the document.
#### Default Value
`false`
#### Inherited from
[`InputDocument`](InputDocument.md).[`autoRepairDisabled`](InputDocument.md#autorepairdisabled)
***
### fileName?
> `optional` **fileName**: `string`
Name for the input document
#### Inherited from
[`InputDocument`](InputDocument.md).[`fileName`](InputDocument.md#filename)
***
### httpOptions?
> `optional` **httpOptions**: [`HttpOptions`](HttpOptions.md)
Options that are applied to a HTTP request.
***
### password?
> `optional` **password**: `string`
The password used for opening the PdfDocument.
#### Inherited from
[`InputDocument`](InputDocument.md).[`password`](InputDocument.md#password)
***
### uri
> **uri**: `string`
The uri where the file can be loaded from.
---
## Interface: PageEventMap
Interface defining event types for `Pdf.Page`.
## Properties
### textFragmentsLoaded()
> **textFragmentsLoaded**: (`textFragments`) => `void`
Event triggered when text fragments of a page are loaded.
The event payload is an array of text fragments.
#### Parameters
• **textFragments**: [`TextFragment`](TextFragment.md)[]
#### Returns
`void`
---
## Interface: PdfImage
An interface representing an image which is registered in a PDF document and can be reused.
## Properties
### id
> **id**: `number`
---
## Interface: SaveOptions
Options used for saving [Pdf.Document](../classes/Document.md)s.
## Properties
### annotationFilter()?
> `optional` **annotationFilter**: (`annotation`) => `boolean`
A callback to be called for each annotation in the document when saving.
The result of the callback determines whether the annotation is included in the output.
Pass `null` to save all annotations.
#### Parameters
• **annotation**: [`Annotation`](../namespaces/Annotations/classes/Annotation.md)
#### Returns
`boolean`
#### Default Value
`undefined`
***
### fileType
> **fileType**: `"Pdf"` \| `"Fdf"`
Choose whether the output file should be a PDF or an FDF document.
#### Default Value
`'Pdf'`
***
### optionalContentFilter()?
> `optional` **optionalContentFilter**: () => `boolean`
#### Returns
`boolean`
#### Default Value
`undefined`
---
## Interface: TextFragment
Represents a text fragment within a document, containing information about its position, content, and layout.
## Properties
### glyphOffsets
> **glyphOffsets**: `number`[]
An array of glyph offsets representing the offset of each character within the text fragment.
Glyph offsets are used for precise positioning and layout purposes.
***
### pageNumber
> **pageNumber**: `number`
The page number where the text fragment is located within the document.
***
### quadrilateral
> **quadrilateral**: [`Quadrilateral`](../namespaces/Geometry/classes/Quadrilateral.md)\<`PdfPoint`\>
A quadrilateral representing the bounding box or area occupied by the text fragment.
This quadrilateral defines the spatial extent of the text fragment on the page.
***
### text
> **text**: `string`
The actual textual content of the text fragment.
---
## Class: `abstract` Action
**`Experimental`**
Base class for actions.
Each subclass represents an interaction the user can perform with the viewer.
For example: Go to a specific point in the document.
## Extended by
- [`GoToAction`](GoToAction.md)
- [`RemoteGoToAction`](RemoteGoToAction.md)
- [`ResetFormAction`](ResetFormAction.md)
- [`SubmitFormAction`](SubmitFormAction.md)
- [`UriAction`](UriAction.md)
## Constructors
### new Action()
> **new Action**(): [`Action`](Action.md)
**`Experimental`**
#### Returns
[`Action`](Action.md)
---
## Class: GoToAction
**`Experimental`**
GoToAction
Go to a specific point in the document.
## Extends
- [`Action`](Action.md)
## Constructors
### new GoToAction()
> **new GoToAction**(): [`GoToAction`](GoToAction.md)
**`Experimental`**
#### Returns
[`GoToAction`](GoToAction.md)
#### Inherited from
[`Action`](Action.md).[`constructor`](Action.md#constructors)
---
## Class: RemoteGoToAction
**`Experimental`**
RemoteGoToAction
Go to some remote location outside the current document.
## Extends
- [`Action`](Action.md)
## Constructors
### new RemoteGoToAction()
> **new RemoteGoToAction**(): [`RemoteGoToAction`](RemoteGoToAction.md)
**`Experimental`**
#### Returns
[`RemoteGoToAction`](RemoteGoToAction.md)
#### Inherited from
[`Action`](Action.md).[`constructor`](Action.md#constructors)
---
## Class: ResetFormAction
**`Experimental`**
ResetFormAction
Reset the current form.
## Extends
- [`Action`](Action.md)
## Constructors
### new ResetFormAction()
> **new ResetFormAction**(): [`ResetFormAction`](ResetFormAction.md)
**`Experimental`**
#### Returns
[`ResetFormAction`](ResetFormAction.md)
#### Inherited from
[`Action`](Action.md).[`constructor`](Action.md#constructors)
---
## Class: SubmitFormAction
**`Experimental`**
SubmitFormAction
Submit the current form.
## Extends
- [`Action`](Action.md)
## Constructors
### new SubmitFormAction()
> **new SubmitFormAction**(): [`SubmitFormAction`](SubmitFormAction.md)
**`Experimental`**
#### Returns
[`SubmitFormAction`](SubmitFormAction.md)
#### Inherited from
[`Action`](Action.md).[`constructor`](Action.md#constructors)
---
## Class: UriAction
**`Experimental`**
UriAction
Go to a specified URI.
## Extends
- [`Action`](Action.md)
## Constructors
### new UriAction()
> **new UriAction**(`uri`): [`UriAction`](UriAction.md)
**`Experimental`**
#### Parameters
• **uri**: `string`
#### Returns
[`UriAction`](UriAction.md)
#### Overrides
[`Action`](Action.md).[`constructor`](Action.md#constructors)
## Properties
### uri
> **uri**: `string`
**`Experimental`**
---
## Actions
## Index
### Classes
- [Action](classes/Action.md)
- [GoToAction](classes/GoToAction.md)
- [RemoteGoToAction](classes/RemoteGoToAction.md)
- [ResetFormAction](classes/ResetFormAction.md)
- [SubmitFormAction](classes/SubmitFormAction.md)
- [UriAction](classes/UriAction.md)
---
## Class: `abstract` Annotation(Classes)
Base class for all annotations.
## Extended by
- [`LinkAnnotation`](LinkAnnotation.md)
- [`MarkupAnnotation`](MarkupAnnotation.md)
- [`WatermarkAnnotation`](WatermarkAnnotation.md)
- [`WidgetAnnotation`](WidgetAnnotation.md)
- [`InternalLinkAnnotation`](InternalLinkAnnotation.md)
## Implements
- [`Disposable`](../../../../Core/interfaces/Disposable.md)
## Constructors
### new Annotation()
> **new Annotation**(`options`): [`Annotation`](Annotation.md)
Creates a new `Annotation` instance.
#### Parameters
• **options**: [`AnnotationOptions`](../interfaces/AnnotationOptions.md)
Options used to initialize annotation.
#### Returns
[`Annotation`](Annotation.md)
## Accessors
### \_\_annotation
> `get` **\_\_annotation**(): `Annotation`
> `set` **\_\_annotation**(`v`): `void`
#### Parameters
• **v**: `Annotation`
#### Returns
`Annotation`
***
### boundingBox
> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
> `set` **boundingBox**(`rectangle`): `void`
#### Parameters
• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Returns
[`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
***
### content
> `get` **content**(): `string`
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
> `set` **content**(`content`): `void`
#### Parameters
• **content**: `string`
#### Returns
`string`
***
### dateModified
> `get` **dateModified**(): `Date`
**`Experimental`**
The date and time when the annotation was most recently modified.
> `set` **dateModified**(`date`): `void`
#### Parameters
• **date**: `Date`
#### Returns
`Date`
***
### hasChanges
> `get` **hasChanges**(): `boolean`
**`Experimental`**
Indicates if the annotation has been changed since the document was opened
#### Returns
`boolean`
***
### hidden
> `get` **hidden**(): `boolean`
If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user.
> `set` **hidden**(`hidden`): `void`
#### Parameters
• **hidden**: `boolean`
#### Returns
`boolean`
***
### id
> `get` **id**(): `void`
**`Experimental`**
A unique identifier for the annotation.
#### Returns
`void`
***
### interactive
> `get` **interactive**(): `boolean`
Specifies whether the annotation allows user interaction.
> `set` **interactive**(`interactive`): `void`
#### Parameters
• **interactive**: `boolean`
#### Returns
`boolean`
***
### isAdded
> `get` **isAdded**(): `boolean`
**`Experimental`**
Indicates whether the annotation was added to a page
#### Returns
`boolean`
***
### isMaintainingAspectRatio
> `get` `abstract` **isMaintainingAspectRatio**(): `boolean`
Indicates if the annotation is maintaining its aspect ratio
#### Returns
`boolean`
***
### isMarkupAnnotation
> `get` `abstract` **isMarkupAnnotation**(): `boolean`
Indicates if the annotation is a markup annotation
#### Returns
`boolean`
***
### isModified
> `get` **isModified**(): `boolean`
**`Experimental`**
Indicates if the annotation has changes that have not yet been saved to
the document
#### Returns
`boolean`
***
### isMoveable
> `get` `abstract` **isMoveable**(): `boolean`
Indicates if the annotation can be moved by the user
#### Returns
`boolean`
***
### isResizable
> `get` `abstract` **isResizable**(): `boolean`
Indicates if the annotation can be resized by the user
#### Returns
`boolean`
***
### isRotatable
> `get` `abstract` **isRotatable**(): `boolean`
Indicates if the annotation can be rotated by the user
#### Returns
`boolean`
***
### isSelectable
> `get` `abstract` **isSelectable**(): `boolean`
Indicates if the annotation can be selected by the user
#### Returns
`boolean`
***
### isWidgetAnnotation
> `get` `abstract` **isWidgetAnnotation**(): `boolean`
Indicates if the annotation is a widget annotation
#### Returns
`boolean`
***
### locked
> `get` **locked**(): [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
Represents the locked state of the annotation.
> `set` **locked**(`locked`): `void`
#### Parameters
• **locked**: [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
#### Returns
[`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
***
### page
> `get` **page**(): [`Page`](../../../classes/Page.md)
Page in which the annotation is embedded.
> `set` **page**(`page`): `void`
Set the page in which the annotation is embedded.
#### Parameters
• **page**: [`Page`](../../../classes/Page.md)
The page to set as the annotation's page.
#### Returns
[`Page`](../../../classes/Page.md)
***
### pageNumber
> `get` **pageNumber**(): `number`
**`Experimental`**
Number of the page in which the annotation is embedded.
#### Returns
`number`
***
### privateData
> `get` **privateData**(): `object`
**`Experimental`**
Custom data to be stored with the annotation
> `set` **privateData**(`privateData`): `void`
#### Parameters
• **privateData**: `object`
#### Returns
`object`
***
### renderProperties
> `get` **renderProperties**(): [`AnnotationRenderProperties`](AnnotationRenderProperties.md)
Object which encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its visibility, interactivity, and other rendering behaviors.
> `set` **renderProperties**(`v`): `void`
#### Parameters
• **v**: [`AnnotationRenderProperties`](AnnotationRenderProperties.md)
#### Returns
[`AnnotationRenderProperties`](AnnotationRenderProperties.md)
***
### source
> `get` **source**(): `void`
**`Experimental`**
Tag that identifies the source the annotation is coming from, if
the source is an input PDF or an input FDF.
Newly created annotations always return `null`.
#### Returns
`void`
***
### type
> `get` `abstract` **type**(): [`AnnotationType`](../enumerations/AnnotationType.md)
The PDF annotation type
#### Returns
[`AnnotationType`](../enumerations/AnnotationType.md)
## Methods
### dispose()
> **dispose**(): `void`
Disposes of the object, releasing any resources it holds.
The `dispose` method is responsible for performing cleanup operations and releasing
any resources acquired by the object. Once an object is disposed, it should not
be used, and attempts to do so may result in undefined behavior.
#### Returns
`void`
#### Implementation of
[`Disposable`](../../../../Core/interfaces/Disposable.md).[`dispose`](../../../../Core/interfaces/Disposable.md#dispose)
---
## Class: AnnotationRenderProperties
The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its rendering behaviors.
## Constructors
### new AnnotationRenderProperties()
> **new AnnotationRenderProperties**(): [`AnnotationRenderProperties`](AnnotationRenderProperties.md)
#### Returns
[`AnnotationRenderProperties`](AnnotationRenderProperties.md)
## Accessors
### fixedRotation
> `get` **fixedRotation**(): `boolean`
Specifies whether the annotation's appearance should remain fixed in orientation when the page is rotated.
> `set` **fixedRotation**(`fixedRotation`): `void`
#### Parameters
• **fixedRotation**: `boolean`
#### Returns
`boolean`
***
### fixedZoom
> `get` **fixedZoom**(): `boolean`
Indicates whether the annotation's appearance should remain fixed in scale when the page's magnification level is changed.
> `set` **fixedZoom**(`fixedZoom`): `void`
#### Parameters
• **fixedZoom**: `boolean`
#### Returns
`boolean`
***
### renderToPrint
> `get` **renderToPrint**(): `boolean`
Specifies whether the annotation should be printed when the page is printed, regardless of its visibility on the screen.
> `set` **renderToPrint**(`renderToPrint`): `void`
#### Parameters
• **renderToPrint**: `boolean`
#### Returns
`boolean`
***
### renderToScreen
> `get` **renderToScreen**(): `boolean`
If set to false, the annotation will not be displayed on the screen and interaction with the user will be disabled.
The annotation may be printed (depending on the setting of the `renderToPrint` flag),
but it should be considered hidden for purposes of onscreen display and user interaction.
> `set` **renderToScreen**(`renderToScreen`): `void`
#### Parameters
• **renderToScreen**: `boolean`
#### Returns
`boolean`
---
## Class: CaretAnnotation
**`Experimental`**
An annotation that marks a point to insert text
## Extends
- [`MarkupAnnotation`](MarkupAnnotation.md)
## Constructors
### new CaretAnnotation()
> **new CaretAnnotation**(`options`): [`CaretAnnotation`](CaretAnnotation.md)
**`Experimental`**
#### Parameters
• **options**: [`CaretAnnotationOptions`](../interfaces/CaretAnnotationOptions.md)
Options used to initialize annotation.
#### Returns
[`CaretAnnotation`](CaretAnnotation.md)
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`constructor`](MarkupAnnotation.md#constructors)
## Accessors
### \_\_annotation
> `get` **\_\_annotation**(): `MarkupAnnotation`
**`Experimental`**
> `set` **\_\_annotation**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: `MarkupAnnotation`
#### Returns
`MarkupAnnotation`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`__annotation`](MarkupAnnotation.md#__annotation)
***
### author
> `get` **author**(): `string`
**`Experimental`**
The author.
> `set` **author**(`author`): `void`
**`Experimental`**
#### Parameters
• **author**: `string`
#### Returns
`string`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`author`](MarkupAnnotation.md#author)
***
### blendMode
> `get` **blendMode**(): [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
**`Experimental`**
blend mode
> `set` **blendMode**(`blendMode`): `void`
**`Experimental`**
#### Parameters
• **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
#### Returns
[`BlendMode`](../../Drawing/enumerations/BlendMode.md)
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`blendMode`](MarkupAnnotation.md#blendmode)
***
### boundingBox
> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
**`Experimental`**
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
> `set` **boundingBox**(`rectangle`): `void`
**`Experimental`**
#### Parameters
• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Returns
[`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`boundingBox`](MarkupAnnotation.md#boundingbox)
***
### content
> `get` **content**(): `string`
**`Experimental`**
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
> `set` **content**(`content`): `void`
**`Experimental`**
#### Parameters
• **content**: `string`
#### Returns
`string`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`content`](MarkupAnnotation.md#content)
***
### creationDate
> `get` **creationDate**(): `Date`
**`Experimental`**
The date and time when the annotation was created.
This property retrieves the creation date from the annotation
and converts it to a JavaScript Date object.
#### Returns
`Date`
The creation date as a JavaScript Date object, or `null` if no
creation date is available in the annotation.
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`creationDate`](MarkupAnnotation.md#creationdate)
***
### dateModified
> `get` **dateModified**(): `Date`
**`Experimental`**
The date and time when the annotation was most recently modified.
> `set` **dateModified**(`date`): `void`
**`Experimental`**
#### Parameters
• **date**: `Date`
#### Returns
`Date`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`dateModified`](MarkupAnnotation.md#datemodified)
***
### hasChanges
> `get` **hasChanges**(): `boolean`
**`Experimental`**
Indicates if the annotation has been changed since the document was opened
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`hasChanges`](MarkupAnnotation.md#haschanges)
***
### hidden
> `get` **hidden**(): `boolean`
**`Experimental`**
If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user.
> `set` **hidden**(`hidden`): `void`
**`Experimental`**
#### Parameters
• **hidden**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`hidden`](MarkupAnnotation.md#hidden)
***
### id
> `get` **id**(): `void`
**`Experimental`**
A unique identifier for the annotation.
#### Returns
`void`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`id`](MarkupAnnotation.md#id)
***
### interactive
> `get` **interactive**(): `boolean`
**`Experimental`**
Specifies whether the annotation allows user interaction.
> `set` **interactive**(`interactive`): `void`
**`Experimental`**
#### Parameters
• **interactive**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`interactive`](MarkupAnnotation.md#interactive)
***
### isAdded
> `get` **isAdded**(): `boolean`
**`Experimental`**
Indicates whether the annotation was added to a page
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`isAdded`](MarkupAnnotation.md#isadded)
***
### isMaintainingAspectRatio
> `get` **isMaintainingAspectRatio**(): `boolean`
**`Experimental`**
Indicates if the annotation is maintaining its aspect ratio
#### Returns
`boolean`
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`isMaintainingAspectRatio`](MarkupAnnotation.md#ismaintainingaspectratio)
***
### isMarkupAnnotation
> `get` **isMarkupAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a markup annotation
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`isMarkupAnnotation`](MarkupAnnotation.md#ismarkupannotation)
***
### isModified
> `get` **isModified**(): `boolean`
**`Experimental`**
Indicates if the annotation has changes that have not yet been saved to
the document
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`isModified`](MarkupAnnotation.md#ismodified)
***
### isMoveable
> `get` **isMoveable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be moved by the user
#### Returns
`boolean`
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`isMoveable`](MarkupAnnotation.md#ismoveable)
***
### isResizable
> `get` **isResizable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be resized by the user
#### Returns
`boolean`
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`isResizable`](MarkupAnnotation.md#isresizable)
***
### isRotatable
> `get` **isRotatable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be rotated by the user
#### Returns
`boolean`
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`isRotatable`](MarkupAnnotation.md#isrotatable)
***
### isSelectable
> `get` **isSelectable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be selected by the user
#### Returns
`boolean`
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`isSelectable`](MarkupAnnotation.md#isselectable)
***
### isWidgetAnnotation
> `get` **isWidgetAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a widget annotation
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`isWidgetAnnotation`](MarkupAnnotation.md#iswidgetannotation)
***
### locked
> `get` **locked**(): [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
**`Experimental`**
Represents the locked state of the annotation.
> `set` **locked**(`locked`): `void`
**`Experimental`**
#### Parameters
• **locked**: [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
#### Returns
[`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`locked`](MarkupAnnotation.md#locked)
***
### modificationDate
> `get` **modificationDate**(): `Date`
**`Experimental`**
The date and time when the annotation was last modified.
This property will retrieve the modification date from the annotation
and convert it to a JavaScript Date object.
#### Returns
`Date`
The modification date as a JavaScript Date object, or `null` if no
modification date is available in the annotation.
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`modificationDate`](MarkupAnnotation.md#modificationdate)
***
### opacity
> `get` **opacity**(): `number`
**`Experimental`**
Annotation opacity
> `set` **opacity**(`opacity`): `void`
**`Experimental`**
#### Parameters
• **opacity**: `number`
#### Returns
`number`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`opacity`](MarkupAnnotation.md#opacity)
***
### page
> `get` **page**(): [`Page`](../../../classes/Page.md)
**`Experimental`**
Page in which the annotation is embedded.
> `set` **page**(`page`): `void`
**`Experimental`**
Set the page in which the annotation is embedded.
#### Parameters
• **page**: [`Page`](../../../classes/Page.md)
The page to set as the annotation's page.
#### Returns
[`Page`](../../../classes/Page.md)
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`page`](MarkupAnnotation.md#page)
***
### pageNumber
> `get` **pageNumber**(): `number`
**`Experimental`**
Number of the page in which the annotation is embedded.
#### Returns
`number`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`pageNumber`](MarkupAnnotation.md#pagenumber)
***
### privateData
> `get` **privateData**(): `object`
**`Experimental`**
Custom data to be stored with the annotation
> `set` **privateData**(`privateData`): `void`
**`Experimental`**
#### Parameters
• **privateData**: `object`
#### Returns
`object`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`privateData`](MarkupAnnotation.md#privatedata)
***
### renderProperties
> `get` **renderProperties**(): [`AnnotationRenderProperties`](AnnotationRenderProperties.md)
**`Experimental`**
Object which encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its visibility, interactivity, and other rendering behaviors.
> `set` **renderProperties**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: [`AnnotationRenderProperties`](AnnotationRenderProperties.md)
#### Returns
[`AnnotationRenderProperties`](AnnotationRenderProperties.md)
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`renderProperties`](MarkupAnnotation.md#renderproperties)
***
### source
> `get` **source**(): `void`
**`Experimental`**
Tag that identifies the source the annotation is coming from, if
the source is an input PDF or an input FDF.
Newly created annotations always return `null`.
#### Returns
`void`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`source`](MarkupAnnotation.md#source)
***
### subject
> `get` **subject**(): `string`
**`Experimental`**
The subject.
> `set` **subject**(`subject`): `void`
**`Experimental`**
#### Parameters
• **subject**: `string`
#### Returns
`string`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`subject`](MarkupAnnotation.md#subject)
***
### type
> `get` **type**(): [`AnnotationType`](../enumerations/AnnotationType.md)
**`Experimental`**
The PDF annotation type
#### Default Value
`AnnotationType.Caret`
#### Returns
[`AnnotationType`](../enumerations/AnnotationType.md)
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`type`](MarkupAnnotation.md#type)
## Methods
### dispose()
> **dispose**(): `void`
**`Experimental`**
#### Returns
`void`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`dispose`](MarkupAnnotation.md#dispose)
---
## Class: `abstract` DrawingAnnotation
**`Experimental`**
Base class for drawing annotations
## Extends
- [`MarkupAnnotation`](MarkupAnnotation.md)
## Extended by
- [`InkAnnotation`](InkAnnotation.md)
- [`LineAnnotation`](LineAnnotation.md)
- [`PolyLineAnnotation`](PolyLineAnnotation.md)
- [`ShapeAnnotation`](ShapeAnnotation.md)
## Constructors
### new DrawingAnnotation()
> **new DrawingAnnotation**(`options`): [`DrawingAnnotation`](DrawingAnnotation.md)
**`Experimental`**
#### Parameters
• **options**: [`DrawingAnnotationOptions`](../interfaces/DrawingAnnotationOptions.md)
Options used to initialize annotation.
#### Returns
[`DrawingAnnotation`](DrawingAnnotation.md)
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`constructor`](MarkupAnnotation.md#constructors)
## Properties
### stroke
> **stroke**: [`Stroke`](../../Drawing/classes/Stroke.md)
**`Experimental`**
## Accessors
### \_\_annotation
> `get` **\_\_annotation**(): `MarkupAnnotation`
**`Experimental`**
> `set` **\_\_annotation**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: `MarkupAnnotation`
#### Returns
`MarkupAnnotation`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`__annotation`](MarkupAnnotation.md#__annotation)
***
### author
> `get` **author**(): `string`
**`Experimental`**
The author.
> `set` **author**(`author`): `void`
**`Experimental`**
#### Parameters
• **author**: `string`
#### Returns
`string`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`author`](MarkupAnnotation.md#author)
***
### blendMode
> `get` **blendMode**(): [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
**`Experimental`**
blend mode
> `set` **blendMode**(`blendMode`): `void`
**`Experimental`**
#### Parameters
• **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
#### Returns
[`BlendMode`](../../Drawing/enumerations/BlendMode.md)
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`blendMode`](MarkupAnnotation.md#blendmode)
***
### boundingBox
> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
**`Experimental`**
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
> `set` **boundingBox**(`rectangle`): `void`
**`Experimental`**
#### Parameters
• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Returns
[`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`boundingBox`](MarkupAnnotation.md#boundingbox)
***
### content
> `get` **content**(): `string`
**`Experimental`**
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
> `set` **content**(`content`): `void`
**`Experimental`**
#### Parameters
• **content**: `string`
#### Returns
`string`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`content`](MarkupAnnotation.md#content)
***
### creationDate
> `get` **creationDate**(): `Date`
**`Experimental`**
The date and time when the annotation was created.
This property retrieves the creation date from the annotation
and converts it to a JavaScript Date object.
#### Returns
`Date`
The creation date as a JavaScript Date object, or `null` if no
creation date is available in the annotation.
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`creationDate`](MarkupAnnotation.md#creationdate)
***
### dateModified
> `get` **dateModified**(): `Date`
**`Experimental`**
The date and time when the annotation was most recently modified.
> `set` **dateModified**(`date`): `void`
**`Experimental`**
#### Parameters
• **date**: `Date`
#### Returns
`Date`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`dateModified`](MarkupAnnotation.md#datemodified)
***
### hasChanges
> `get` **hasChanges**(): `boolean`
**`Experimental`**
Indicates if the annotation has been changed since the document was opened
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`hasChanges`](MarkupAnnotation.md#haschanges)
***
### hidden
> `get` **hidden**(): `boolean`
**`Experimental`**
If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user.
> `set` **hidden**(`hidden`): `void`
**`Experimental`**
#### Parameters
• **hidden**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`hidden`](MarkupAnnotation.md#hidden)
***
### id
> `get` **id**(): `void`
**`Experimental`**
A unique identifier for the annotation.
#### Returns
`void`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`id`](MarkupAnnotation.md#id)
***
### interactive
> `get` **interactive**(): `boolean`
**`Experimental`**
Specifies whether the annotation allows user interaction.
> `set` **interactive**(`interactive`): `void`
**`Experimental`**
#### Parameters
• **interactive**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`interactive`](MarkupAnnotation.md#interactive)
***
### isAdded
> `get` **isAdded**(): `boolean`
**`Experimental`**
Indicates whether the annotation was added to a page
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`isAdded`](MarkupAnnotation.md#isadded)
***
### isMaintainingAspectRatio
> `get` **isMaintainingAspectRatio**(): `boolean`
**`Experimental`**
Indicates if the annotation is maintaining its aspect ratio
#### Returns
`boolean`
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`isMaintainingAspectRatio`](MarkupAnnotation.md#ismaintainingaspectratio)
***
### isMarkupAnnotation
> `get` **isMarkupAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a markup annotation
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`isMarkupAnnotation`](MarkupAnnotation.md#ismarkupannotation)
***
### isModified
> `get` **isModified**(): `boolean`
**`Experimental`**
Indicates if the annotation has changes that have not yet been saved to
the document
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`isModified`](MarkupAnnotation.md#ismodified)
***
### isMoveable
> `get` **isMoveable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be moved by the user
#### Returns
`boolean`
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`isMoveable`](MarkupAnnotation.md#ismoveable)
***
### isResizable
> `get` **isResizable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be resized by the user
#### Returns
`boolean`
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`isResizable`](MarkupAnnotation.md#isresizable)
***
### isRotatable
> `get` **isRotatable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be rotated by the user
#### Returns
`boolean`
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`isRotatable`](MarkupAnnotation.md#isrotatable)
***
### isSelectable
> `get` **isSelectable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be selected by the user
#### Returns
`boolean`
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`isSelectable`](MarkupAnnotation.md#isselectable)
***
### isWidgetAnnotation
> `get` **isWidgetAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a widget annotation
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`isWidgetAnnotation`](MarkupAnnotation.md#iswidgetannotation)
***
### locked
> `get` **locked**(): [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
**`Experimental`**
Represents the locked state of the annotation.
> `set` **locked**(`locked`): `void`
**`Experimental`**
#### Parameters
• **locked**: [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
#### Returns
[`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`locked`](MarkupAnnotation.md#locked)
***
### modificationDate
> `get` **modificationDate**(): `Date`
**`Experimental`**
The date and time when the annotation was last modified.
This property will retrieve the modification date from the annotation
and convert it to a JavaScript Date object.
#### Returns
`Date`
The modification date as a JavaScript Date object, or `null` if no
modification date is available in the annotation.
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`modificationDate`](MarkupAnnotation.md#modificationdate)
***
### opacity
> `get` **opacity**(): `number`
**`Experimental`**
Annotation opacity
> `set` **opacity**(`opacity`): `void`
**`Experimental`**
#### Parameters
• **opacity**: `number`
#### Returns
`number`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`opacity`](MarkupAnnotation.md#opacity)
***
### page
> `get` **page**(): [`Page`](../../../classes/Page.md)
**`Experimental`**
Page in which the annotation is embedded.
> `set` **page**(`page`): `void`
**`Experimental`**
Set the page in which the annotation is embedded.
#### Parameters
• **page**: [`Page`](../../../classes/Page.md)
The page to set as the annotation's page.
#### Returns
[`Page`](../../../classes/Page.md)
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`page`](MarkupAnnotation.md#page)
***
### pageNumber
> `get` **pageNumber**(): `number`
**`Experimental`**
Number of the page in which the annotation is embedded.
#### Returns
`number`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`pageNumber`](MarkupAnnotation.md#pagenumber)
***
### privateData
> `get` **privateData**(): `object`
**`Experimental`**
Custom data to be stored with the annotation
> `set` **privateData**(`privateData`): `void`
**`Experimental`**
#### Parameters
• **privateData**: `object`
#### Returns
`object`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`privateData`](MarkupAnnotation.md#privatedata)
***
### renderProperties
> `get` **renderProperties**(): [`AnnotationRenderProperties`](AnnotationRenderProperties.md)
**`Experimental`**
Object which encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its visibility, interactivity, and other rendering behaviors.
> `set` **renderProperties**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: [`AnnotationRenderProperties`](AnnotationRenderProperties.md)
#### Returns
[`AnnotationRenderProperties`](AnnotationRenderProperties.md)
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`renderProperties`](MarkupAnnotation.md#renderproperties)
***
### source
> `get` **source**(): `void`
**`Experimental`**
Tag that identifies the source the annotation is coming from, if
the source is an input PDF or an input FDF.
Newly created annotations always return `null`.
#### Returns
`void`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`source`](MarkupAnnotation.md#source)
***
### subject
> `get` **subject**(): `string`
**`Experimental`**
The subject.
> `set` **subject**(`subject`): `void`
**`Experimental`**
#### Parameters
• **subject**: `string`
#### Returns
`string`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`subject`](MarkupAnnotation.md#subject)
***
### type
> `get` `abstract` **type**(): [`AnnotationType`](../enumerations/AnnotationType.md)
**`Experimental`**
The PDF annotation type
#### Returns
[`AnnotationType`](../enumerations/AnnotationType.md)
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`type`](MarkupAnnotation.md#type)
## Methods
### dispose()
> **dispose**(): `void`
**`Experimental`**
#### Returns
`void`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`dispose`](MarkupAnnotation.md#dispose)
---
## Class: EllipseAnnotation
**`Experimental`**
An ellipse drawing annotation
## Extends
- [`ShapeAnnotation`](ShapeAnnotation.md)
## Constructors
### new EllipseAnnotation()
> **new EllipseAnnotation**(`options`): [`EllipseAnnotation`](EllipseAnnotation.md)
**`Experimental`**
#### Parameters
• **options**: [`EllipseAnnotationOptions`](../interfaces/EllipseAnnotationOptions.md)
Options used to initialize annotation.
#### Returns
[`EllipseAnnotation`](EllipseAnnotation.md)
#### Overrides
[`ShapeAnnotation`](ShapeAnnotation.md).[`constructor`](ShapeAnnotation.md#constructors)
## Properties
### stroke
> **stroke**: [`Stroke`](../../Drawing/classes/Stroke.md)
**`Experimental`**
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`stroke`](ShapeAnnotation.md#stroke)
## Accessors
### \_\_annotation
> `get` **\_\_annotation**(): `MarkupAnnotation`
**`Experimental`**
> `set` **\_\_annotation**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: `MarkupAnnotation`
#### Returns
`MarkupAnnotation`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`__annotation`](ShapeAnnotation.md#__annotation)
***
### author
> `get` **author**(): `string`
**`Experimental`**
The author.
> `set` **author**(`author`): `void`
**`Experimental`**
#### Parameters
• **author**: `string`
#### Returns
`string`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`author`](ShapeAnnotation.md#author)
***
### blendMode
> `get` **blendMode**(): [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
**`Experimental`**
blend mode
> `set` **blendMode**(`blendMode`): `void`
**`Experimental`**
#### Parameters
• **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
#### Returns
[`BlendMode`](../../Drawing/enumerations/BlendMode.md)
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`blendMode`](ShapeAnnotation.md#blendmode)
***
### borderEffect
> `get` **borderEffect**(): `BorderEffect`
**`Experimental`**
Gets the border effect of the ellipse annotation.
> `set` **borderEffect**(`value`): `void`
**`Experimental`**
Sets the border effect of the ellipse annotation.
#### Parameters
• **value**: `BorderEffect`
#### Returns
`BorderEffect`
***
### borderIntensity
> `get` **borderIntensity**(): `number`
**`Experimental`**
Gets the border intensity of the ellipse annotation.
> `set` **borderIntensity**(`value`): `void`
**`Experimental`**
Sets the border intensity of the ellipse annotation.
#### Parameters
• **value**: `number`
#### Returns
`number`
***
### boundingBox
> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
**`Experimental`**
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
> `set` **boundingBox**(`rectangle`): `void`
**`Experimental`**
#### Parameters
• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Returns
[`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`boundingBox`](ShapeAnnotation.md#boundingbox)
***
### content
> `get` **content**(): `string`
**`Experimental`**
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
> `set` **content**(`content`): `void`
**`Experimental`**
#### Parameters
• **content**: `string`
#### Returns
`string`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`content`](ShapeAnnotation.md#content)
***
### creationDate
> `get` **creationDate**(): `Date`
**`Experimental`**
The date and time when the annotation was created.
This property retrieves the creation date from the annotation
and converts it to a JavaScript Date object.
#### Returns
`Date`
The creation date as a JavaScript Date object, or `null` if no
creation date is available in the annotation.
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`creationDate`](ShapeAnnotation.md#creationdate)
***
### dateModified
> `get` **dateModified**(): `Date`
**`Experimental`**
The date and time when the annotation was most recently modified.
> `set` **dateModified**(`date`): `void`
**`Experimental`**
#### Parameters
• **date**: `Date`
#### Returns
`Date`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`dateModified`](ShapeAnnotation.md#datemodified)
***
### fillColor
> `get` **fillColor**(): [`RgbaColor`](../../Drawing/classes/RgbaColor.md)
**`Experimental`**
Gets the fill color of the ellipse annotation.
> `set` **fillColor**(`value`): `void`
**`Experimental`**
Sets the fill color of the ellipse annotation.
#### Parameters
• **value**: [`RgbaColor`](../../Drawing/classes/RgbaColor.md)
#### Returns
[`RgbaColor`](../../Drawing/classes/RgbaColor.md)
***
### hasChanges
> `get` **hasChanges**(): `boolean`
**`Experimental`**
Indicates if the annotation has been changed since the document was opened
#### Returns
`boolean`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`hasChanges`](ShapeAnnotation.md#haschanges)
***
### hidden
> `get` **hidden**(): `boolean`
**`Experimental`**
If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user.
> `set` **hidden**(`hidden`): `void`
**`Experimental`**
#### Parameters
• **hidden**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`hidden`](ShapeAnnotation.md#hidden)
***
### id
> `get` **id**(): `void`
**`Experimental`**
A unique identifier for the annotation.
#### Returns
`void`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`id`](ShapeAnnotation.md#id)
***
### interactive
> `get` **interactive**(): `boolean`
**`Experimental`**
Specifies whether the annotation allows user interaction.
> `set` **interactive**(`interactive`): `void`
**`Experimental`**
#### Parameters
• **interactive**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`interactive`](ShapeAnnotation.md#interactive)
***
### isAdded
> `get` **isAdded**(): `boolean`
**`Experimental`**
Indicates whether the annotation was added to a page
#### Returns
`boolean`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`isAdded`](ShapeAnnotation.md#isadded)
***
### isMaintainingAspectRatio
> `get` **isMaintainingAspectRatio**(): `boolean`
**`Experimental`**
Indicates if the annotation is maintaining its aspect ratio
#### Returns
`boolean`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`isMaintainingAspectRatio`](ShapeAnnotation.md#ismaintainingaspectratio)
***
### isMarkupAnnotation
> `get` **isMarkupAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a markup annotation
#### Returns
`boolean`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`isMarkupAnnotation`](ShapeAnnotation.md#ismarkupannotation)
***
### isModified
> `get` **isModified**(): `boolean`
**`Experimental`**
Indicates if the annotation has changes that have not yet been saved to
the document
#### Returns
`boolean`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`isModified`](ShapeAnnotation.md#ismodified)
***
### isMoveable
> `get` **isMoveable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be moved by the user
#### Returns
`boolean`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`isMoveable`](ShapeAnnotation.md#ismoveable)
***
### isResizable
> `get` **isResizable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be resized by the user
#### Returns
`boolean`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`isResizable`](ShapeAnnotation.md#isresizable)
***
### isRotatable
> `get` **isRotatable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be rotated by the user
#### Returns
`boolean`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`isRotatable`](ShapeAnnotation.md#isrotatable)
***
### isSelectable
> `get` **isSelectable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be selected by the user
#### Returns
`boolean`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`isSelectable`](ShapeAnnotation.md#isselectable)
***
### isWidgetAnnotation
> `get` **isWidgetAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a widget annotation
#### Returns
`boolean`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`isWidgetAnnotation`](ShapeAnnotation.md#iswidgetannotation)
***
### lineColor
> `get` **lineColor**(): [`RgbaColor`](../../Drawing/classes/RgbaColor.md)
**`Experimental`**
Gets the line color of the ellipse annotation.
> `set` **lineColor**(`value`): `void`
**`Experimental`**
Sets the line color of the ellipse annotation.
#### Parameters
• **value**: [`RgbaColor`](../../Drawing/classes/RgbaColor.md)
#### Returns
[`RgbaColor`](../../Drawing/classes/RgbaColor.md)
***
### lineWidth
> `get` **lineWidth**(): `number`
**`Experimental`**
Gets the line width of the ellipse annotation.
> `set` **lineWidth**(`value`): `void`
**`Experimental`**
Sets the line width of the ellipse annotation.
#### Parameters
• **value**: `number`
#### Returns
`number`
***
### locked
> `get` **locked**(): [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
**`Experimental`**
Represents the locked state of the annotation.
> `set` **locked**(`locked`): `void`
**`Experimental`**
#### Parameters
• **locked**: [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
#### Returns
[`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`locked`](ShapeAnnotation.md#locked)
***
### modificationDate
> `get` **modificationDate**(): `Date`
**`Experimental`**
The date and time when the annotation was last modified.
This property will retrieve the modification date from the annotation
and convert it to a JavaScript Date object.
#### Returns
`Date`
The modification date as a JavaScript Date object, or `null` if no
modification date is available in the annotation.
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`modificationDate`](ShapeAnnotation.md#modificationdate)
***
### opacity
> `get` **opacity**(): `number`
**`Experimental`**
Annotation opacity
> `set` **opacity**(`opacity`): `void`
**`Experimental`**
#### Parameters
• **opacity**: `number`
#### Returns
`number`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`opacity`](ShapeAnnotation.md#opacity)
***
### page
> `get` **page**(): [`Page`](../../../classes/Page.md)
**`Experimental`**
Page in which the annotation is embedded.
> `set` **page**(`page`): `void`
**`Experimental`**
Set the page in which the annotation is embedded.
#### Parameters
• **page**: [`Page`](../../../classes/Page.md)
The page to set as the annotation's page.
#### Returns
[`Page`](../../../classes/Page.md)
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`page`](ShapeAnnotation.md#page)
***
### pageNumber
> `get` **pageNumber**(): `number`
**`Experimental`**
Number of the page in which the annotation is embedded.
#### Returns
`number`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`pageNumber`](ShapeAnnotation.md#pagenumber)
***
### privateData
> `get` **privateData**(): `object`
**`Experimental`**
Custom data to be stored with the annotation
> `set` **privateData**(`privateData`): `void`
**`Experimental`**
#### Parameters
• **privateData**: `object`
#### Returns
`object`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`privateData`](ShapeAnnotation.md#privatedata)
***
### renderProperties
> `get` **renderProperties**(): [`AnnotationRenderProperties`](AnnotationRenderProperties.md)
**`Experimental`**
Object which encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its visibility, interactivity, and other rendering behaviors.
> `set` **renderProperties**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: [`AnnotationRenderProperties`](AnnotationRenderProperties.md)
#### Returns
[`AnnotationRenderProperties`](AnnotationRenderProperties.md)
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`renderProperties`](ShapeAnnotation.md#renderproperties)
***
### source
> `get` **source**(): `void`
**`Experimental`**
Tag that identifies the source the annotation is coming from, if
the source is an input PDF or an input FDF.
Newly created annotations always return `null`.
#### Returns
`void`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`source`](ShapeAnnotation.md#source)
***
### subject
> `get` **subject**(): `string`
**`Experimental`**
The subject.
> `set` **subject**(`subject`): `void`
**`Experimental`**
#### Parameters
• **subject**: `string`
#### Returns
`string`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`subject`](ShapeAnnotation.md#subject)
***
### type
> `get` **type**(): [`AnnotationType`](../enumerations/AnnotationType.md)
**`Experimental`**
The PDF annotation type
#### Returns
[`AnnotationType`](../enumerations/AnnotationType.md)
#### Overrides
[`ShapeAnnotation`](ShapeAnnotation.md).[`type`](ShapeAnnotation.md#type)
## Methods
### dispose()
> **dispose**(): `void`
**`Experimental`**
#### Returns
`void`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`dispose`](ShapeAnnotation.md#dispose)
---
## Class: `abstract` FileAttachmentAnnotation
**`Experimental`**
A file attachment annotation
## Remarks
A file attachment annotation (PDF 1.3) contains a reference to a file,
which typically is embedded in the PDF file.
## Extends
- [`MarkupAnnotation`](MarkupAnnotation.md)
## Constructors
### new FileAttachmentAnnotation()
> **new FileAttachmentAnnotation**(`options`): [`FileAttachmentAnnotation`](FileAttachmentAnnotation.md)
**`Experimental`**
#### Parameters
• **options**: [`FileAttachmentAnnotationOptions`](../interfaces/FileAttachmentAnnotationOptions.md)
Options used to initialize annotation.
#### Returns
[`FileAttachmentAnnotation`](FileAttachmentAnnotation.md)
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`constructor`](MarkupAnnotation.md#constructors)
## Properties
### icon
> **icon**: [`FileAttachmentAnnotationIcon`](../enumerations/FileAttachmentAnnotationIcon.md)
**`Experimental`**
The icon to be used in displaying the annotation.
## Accessors
### \_\_annotation
> `get` **\_\_annotation**(): `MarkupAnnotation`
**`Experimental`**
> `set` **\_\_annotation**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: `MarkupAnnotation`
#### Returns
`MarkupAnnotation`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`__annotation`](MarkupAnnotation.md#__annotation)
***
### author
> `get` **author**(): `string`
**`Experimental`**
The author.
> `set` **author**(`author`): `void`
**`Experimental`**
#### Parameters
• **author**: `string`
#### Returns
`string`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`author`](MarkupAnnotation.md#author)
***
### blendMode
> `get` **blendMode**(): [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
**`Experimental`**
blend mode
> `set` **blendMode**(`blendMode`): `void`
**`Experimental`**
#### Parameters
• **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
#### Returns
[`BlendMode`](../../Drawing/enumerations/BlendMode.md)
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`blendMode`](MarkupAnnotation.md#blendmode)
***
### boundingBox
> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
**`Experimental`**
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
> `set` **boundingBox**(`rectangle`): `void`
**`Experimental`**
#### Parameters
• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Returns
[`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`boundingBox`](MarkupAnnotation.md#boundingbox)
***
### content
> `get` **content**(): `string`
**`Experimental`**
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
> `set` **content**(`content`): `void`
**`Experimental`**
#### Parameters
• **content**: `string`
#### Returns
`string`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`content`](MarkupAnnotation.md#content)
***
### creationDate
> `get` **creationDate**(): `Date`
**`Experimental`**
The date and time when the annotation was created.
This property retrieves the creation date from the annotation
and converts it to a JavaScript Date object.
#### Returns
`Date`
The creation date as a JavaScript Date object, or `null` if no
creation date is available in the annotation.
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`creationDate`](MarkupAnnotation.md#creationdate)
***
### dateModified
> `get` **dateModified**(): `Date`
**`Experimental`**
The date and time when the annotation was most recently modified.
> `set` **dateModified**(`date`): `void`
**`Experimental`**
#### Parameters
• **date**: `Date`
#### Returns
`Date`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`dateModified`](MarkupAnnotation.md#datemodified)
***
### hasChanges
> `get` **hasChanges**(): `boolean`
**`Experimental`**
Indicates if the annotation has been changed since the document was opened
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`hasChanges`](MarkupAnnotation.md#haschanges)
***
### hidden
> `get` **hidden**(): `boolean`
**`Experimental`**
If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user.
> `set` **hidden**(`hidden`): `void`
**`Experimental`**
#### Parameters
• **hidden**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`hidden`](MarkupAnnotation.md#hidden)
***
### id
> `get` **id**(): `void`
**`Experimental`**
A unique identifier for the annotation.
#### Returns
`void`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`id`](MarkupAnnotation.md#id)
***
### interactive
> `get` **interactive**(): `boolean`
**`Experimental`**
Specifies whether the annotation allows user interaction.
> `set` **interactive**(`interactive`): `void`
**`Experimental`**
#### Parameters
• **interactive**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`interactive`](MarkupAnnotation.md#interactive)
***
### isAdded
> `get` **isAdded**(): `boolean`
**`Experimental`**
Indicates whether the annotation was added to a page
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`isAdded`](MarkupAnnotation.md#isadded)
***
### isMaintainingAspectRatio
> `get` **isMaintainingAspectRatio**(): `boolean`
**`Experimental`**
Indicates if the annotation is maintaining its aspect ratio
#### Returns
`boolean`
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`isMaintainingAspectRatio`](MarkupAnnotation.md#ismaintainingaspectratio)
***
### isMarkupAnnotation
> `get` **isMarkupAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a markup annotation
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`isMarkupAnnotation`](MarkupAnnotation.md#ismarkupannotation)
***
### isModified
> `get` **isModified**(): `boolean`
**`Experimental`**
Indicates if the annotation has changes that have not yet been saved to
the document
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`isModified`](MarkupAnnotation.md#ismodified)
***
### isMoveable
> `get` **isMoveable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be moved by the user
#### Returns
`boolean`
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`isMoveable`](MarkupAnnotation.md#ismoveable)
***
### isResizable
> `get` **isResizable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be resized by the user
#### Returns
`boolean`
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`isResizable`](MarkupAnnotation.md#isresizable)
***
### isRotatable
> `get` **isRotatable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be rotated by the user
#### Returns
`boolean`
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`isRotatable`](MarkupAnnotation.md#isrotatable)
***
### isSelectable
> `get` **isSelectable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be selected by the user
#### Returns
`boolean`
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`isSelectable`](MarkupAnnotation.md#isselectable)
***
### isWidgetAnnotation
> `get` **isWidgetAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a widget annotation
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`isWidgetAnnotation`](MarkupAnnotation.md#iswidgetannotation)
***
### locked
> `get` **locked**(): [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
**`Experimental`**
Represents the locked state of the annotation.
> `set` **locked**(`locked`): `void`
**`Experimental`**
#### Parameters
• **locked**: [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
#### Returns
[`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`locked`](MarkupAnnotation.md#locked)
***
### modificationDate
> `get` **modificationDate**(): `Date`
**`Experimental`**
The date and time when the annotation was last modified.
This property will retrieve the modification date from the annotation
and convert it to a JavaScript Date object.
#### Returns
`Date`
The modification date as a JavaScript Date object, or `null` if no
modification date is available in the annotation.
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`modificationDate`](MarkupAnnotation.md#modificationdate)
***
### opacity
> `get` **opacity**(): `number`
**`Experimental`**
Annotation opacity
> `set` **opacity**(`opacity`): `void`
**`Experimental`**
#### Parameters
• **opacity**: `number`
#### Returns
`number`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`opacity`](MarkupAnnotation.md#opacity)
***
### page
> `get` **page**(): [`Page`](../../../classes/Page.md)
**`Experimental`**
Page in which the annotation is embedded.
> `set` **page**(`page`): `void`
**`Experimental`**
Set the page in which the annotation is embedded.
#### Parameters
• **page**: [`Page`](../../../classes/Page.md)
The page to set as the annotation's page.
#### Returns
[`Page`](../../../classes/Page.md)
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`page`](MarkupAnnotation.md#page)
***
### pageNumber
> `get` **pageNumber**(): `number`
**`Experimental`**
Number of the page in which the annotation is embedded.
#### Returns
`number`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`pageNumber`](MarkupAnnotation.md#pagenumber)
***
### privateData
> `get` **privateData**(): `object`
**`Experimental`**
Custom data to be stored with the annotation
> `set` **privateData**(`privateData`): `void`
**`Experimental`**
#### Parameters
• **privateData**: `object`
#### Returns
`object`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`privateData`](MarkupAnnotation.md#privatedata)
***
### renderProperties
> `get` **renderProperties**(): [`AnnotationRenderProperties`](AnnotationRenderProperties.md)
**`Experimental`**
Object which encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its visibility, interactivity, and other rendering behaviors.
> `set` **renderProperties**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: [`AnnotationRenderProperties`](AnnotationRenderProperties.md)
#### Returns
[`AnnotationRenderProperties`](AnnotationRenderProperties.md)
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`renderProperties`](MarkupAnnotation.md#renderproperties)
***
### source
> `get` **source**(): `void`
**`Experimental`**
Tag that identifies the source the annotation is coming from, if
the source is an input PDF or an input FDF.
Newly created annotations always return `null`.
#### Returns
`void`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`source`](MarkupAnnotation.md#source)
***
### subject
> `get` **subject**(): `string`
**`Experimental`**
The subject.
> `set` **subject**(`subject`): `void`
**`Experimental`**
#### Parameters
• **subject**: `string`
#### Returns
`string`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`subject`](MarkupAnnotation.md#subject)
***
### type
> `get` **type**(): [`AnnotationType`](../enumerations/AnnotationType.md)
**`Experimental`**
The PDF annotation type
#### Returns
[`AnnotationType`](../enumerations/AnnotationType.md)
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`type`](MarkupAnnotation.md#type)
## Methods
### dispose()
> **dispose**(): `void`
**`Experimental`**
#### Returns
`void`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`dispose`](MarkupAnnotation.md#dispose)
---
## Class: FreeTextAnnotation
An annotation that displays text
For a free-text annotation, the annotation's content is used as text to be
displayed as the annotation's visual manifestation on the page.
## Extends
- [`MarkupAnnotation`](MarkupAnnotation.md)
## Constructors
### new FreeTextAnnotation()
> **new FreeTextAnnotation**(`options`): [`FreeTextAnnotation`](FreeTextAnnotation.md)
Creates a new `FreeTextAnnotation` instance.
#### Parameters
• **options**: [`FreeTextAnnotationOptions`](../interfaces/FreeTextAnnotationOptions.md)
Options used to initialize annotation.
#### Returns
[`FreeTextAnnotation`](FreeTextAnnotation.md)
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`constructor`](MarkupAnnotation.md#constructors)
## Accessors
### \_\_annotation
> `get` **\_\_annotation**(): `FreeTextAnnotation`
> `set` **\_\_annotation**(`v`): `void`
#### Parameters
• **v**: `FreeTextAnnotation`
#### Returns
`FreeTextAnnotation`
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`__annotation`](MarkupAnnotation.md#__annotation)
***
### author
> `get` **author**(): `string`
The author.
> `set` **author**(`author`): `void`
#### Parameters
• **author**: `string`
#### Returns
`string`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`author`](MarkupAnnotation.md#author)
***
### backgroundColor
> `get` **backgroundColor**(): `string`
Background color for the annotation.
> `set` **backgroundColor**(`color`): `void`
#### Parameters
• **color**: `string`
#### Returns
`string`
***
### blendMode
> `get` **blendMode**(): [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
**`Experimental`**
blend mode
> `set` **blendMode**(`blendMode`): `void`
#### Parameters
• **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
#### Returns
[`BlendMode`](../../Drawing/enumerations/BlendMode.md)
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`blendMode`](MarkupAnnotation.md#blendmode)
***
### boundingBox
> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
> `set` **boundingBox**(`rectangle`): `void`
#### Parameters
• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Returns
[`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`boundingBox`](MarkupAnnotation.md#boundingbox)
***
### content
> `get` **content**(): `string`
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
> `set` **content**(`content`): `void`
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
#### Parameters
• **content**: `string`
#### Returns
`string`
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`content`](MarkupAnnotation.md#content)
***
### creationDate
> `get` **creationDate**(): `Date`
The date and time when the annotation was created.
This property retrieves the creation date from the annotation
and converts it to a JavaScript Date object.
#### Returns
`Date`
The creation date as a JavaScript Date object, or `null` if no
creation date is available in the annotation.
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`creationDate`](MarkupAnnotation.md#creationdate)
***
### dateModified
> `get` **dateModified**(): `Date`
**`Experimental`**
The date and time when the annotation was most recently modified.
> `set` **dateModified**(`date`): `void`
#### Parameters
• **date**: `Date`
#### Returns
`Date`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`dateModified`](MarkupAnnotation.md#datemodified)
***
### hasChanges
> `get` **hasChanges**(): `boolean`
**`Experimental`**
Indicates if the annotation has been changed since the document was opened
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`hasChanges`](MarkupAnnotation.md#haschanges)
***
### hidden
> `get` **hidden**(): `boolean`
If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user.
> `set` **hidden**(`hidden`): `void`
#### Parameters
• **hidden**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`hidden`](MarkupAnnotation.md#hidden)
***
### id
> `get` **id**(): `void`
**`Experimental`**
A unique identifier for the annotation.
#### Returns
`void`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`id`](MarkupAnnotation.md#id)
***
### interactive
> `get` **interactive**(): `boolean`
Specifies whether the annotation allows user interaction.
> `set` **interactive**(`interactive`): `void`
#### Parameters
• **interactive**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`interactive`](MarkupAnnotation.md#interactive)
***
### isAdded
> `get` **isAdded**(): `boolean`
**`Experimental`**
Indicates whether the annotation was added to a page
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`isAdded`](MarkupAnnotation.md#isadded)
***
### isMaintainingAspectRatio
> `get` **isMaintainingAspectRatio**(): `boolean`
Indicates if the annotation is maintaining its aspect ratio
#### Returns
`boolean`
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`isMaintainingAspectRatio`](MarkupAnnotation.md#ismaintainingaspectratio)
***
### isMarkupAnnotation
> `get` **isMarkupAnnotation**(): `boolean`
Indicates if the annotation is a markup annotation
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`isMarkupAnnotation`](MarkupAnnotation.md#ismarkupannotation)
***
### isModified
> `get` **isModified**(): `boolean`
**`Experimental`**
Indicates if the annotation has changes that have not yet been saved to
the document
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`isModified`](MarkupAnnotation.md#ismodified)
***
### isMoveable
> `get` **isMoveable**(): `boolean`
Indicates if the annotation can be moved by the user
#### Returns
`boolean`
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`isMoveable`](MarkupAnnotation.md#ismoveable)
***
### isResizable
> `get` **isResizable**(): `boolean`
Indicates if the annotation can be resized by the user
#### Returns
`boolean`
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`isResizable`](MarkupAnnotation.md#isresizable)
***
### isRotatable
> `get` **isRotatable**(): `boolean`
Indicates if the annotation can be rotated by the user
#### Returns
`boolean`
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`isRotatable`](MarkupAnnotation.md#isrotatable)
***
### isSelectable
> `get` **isSelectable**(): `boolean`
Indicates if the annotation can be selected by the user
#### Returns
`boolean`
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`isSelectable`](MarkupAnnotation.md#isselectable)
***
### isWidgetAnnotation
> `get` **isWidgetAnnotation**(): `boolean`
Indicates if the annotation is a widget annotation
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`isWidgetAnnotation`](MarkupAnnotation.md#iswidgetannotation)
***
### locked
> `get` **locked**(): [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
Represents the locked state of the annotation.
> `set` **locked**(`locked`): `void`
#### Parameters
• **locked**: [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
#### Returns
[`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`locked`](MarkupAnnotation.md#locked)
***
### modificationDate
> `get` **modificationDate**(): `Date`
The date and time when the annotation was last modified.
This property will retrieve the modification date from the annotation
and convert it to a JavaScript Date object.
#### Returns
`Date`
The modification date as a JavaScript Date object, or `null` if no
modification date is available in the annotation.
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`modificationDate`](MarkupAnnotation.md#modificationdate)
***
### opacity
> `get` **opacity**(): `number`
**`Experimental`**
Annotation opacity
> `set` **opacity**(`opacity`): `void`
#### Parameters
• **opacity**: `number`
#### Returns
`number`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`opacity`](MarkupAnnotation.md#opacity)
***
### page
> `get` **page**(): [`Page`](../../../classes/Page.md)
Page in which the annotation is embedded.
> `set` **page**(`page`): `void`
Set the page in which the annotation is embedded.
#### Parameters
• **page**: [`Page`](../../../classes/Page.md)
The page to set as the annotation's page.
#### Returns
[`Page`](../../../classes/Page.md)
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`page`](MarkupAnnotation.md#page)
***
### pageNumber
> `get` **pageNumber**(): `number`
**`Experimental`**
Number of the page in which the annotation is embedded.
#### Returns
`number`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`pageNumber`](MarkupAnnotation.md#pagenumber)
***
### privateData
> `get` **privateData**(): `object`
**`Experimental`**
Custom data to be stored with the annotation
> `set` **privateData**(`privateData`): `void`
#### Parameters
• **privateData**: `object`
#### Returns
`object`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`privateData`](MarkupAnnotation.md#privatedata)
***
### renderProperties
> `get` **renderProperties**(): [`AnnotationRenderProperties`](AnnotationRenderProperties.md)
Object which encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its visibility, interactivity, and other rendering behaviors.
> `set` **renderProperties**(`v`): `void`
#### Parameters
• **v**: [`AnnotationRenderProperties`](AnnotationRenderProperties.md)
#### Returns
[`AnnotationRenderProperties`](AnnotationRenderProperties.md)
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`renderProperties`](MarkupAnnotation.md#renderproperties)
***
### richText
> `get` **richText**(): `string`
A rich text string that shall be displayed in the popup window when the
annotation is opened.
> `set` **richText**(`richText`): `void`
#### Parameters
• **richText**: `string`
#### Returns
`string`
***
### rotation
> `get` **rotation**(): [`Rotation`](../../../enumerations/Rotation.md)
Rotation of the annotation
> `set` **rotation**(`rotation`): `void`
#### Parameters
• **rotation**: [`Rotation`](../../../enumerations/Rotation.md)
#### Returns
[`Rotation`](../../../enumerations/Rotation.md)
***
### source
> `get` **source**(): `void`
**`Experimental`**
Tag that identifies the source the annotation is coming from, if
the source is an input PDF or an input FDF.
Newly created annotations always return `null`.
#### Returns
`void`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`source`](MarkupAnnotation.md#source)
***
### subject
> `get` **subject**(): `string`
The subject.
> `set` **subject**(`subject`): `void`
#### Parameters
• **subject**: `string`
#### Returns
`string`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`subject`](MarkupAnnotation.md#subject)
***
### type
> `get` **type**(): [`AnnotationType`](../enumerations/AnnotationType.md)
The PDF annotation type
#### Returns
[`AnnotationType`](../enumerations/AnnotationType.md)
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`type`](MarkupAnnotation.md#type)
## Methods
### dispose()
> **dispose**(): `void`
Disposes of the object, releasing any resources it holds.
The `dispose` method is responsible for performing cleanup operations and releasing
any resources acquired by the object. Once an object is disposed, it should not
be used, and attempts to do so may result in undefined behavior.
#### Returns
`void`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`dispose`](MarkupAnnotation.md#dispose)
---
## Class: InkAnnotation
**`Experimental`**
A free-hand drawing annotation
## Extends
- [`DrawingAnnotation`](DrawingAnnotation.md)
## Constructors
### new InkAnnotation()
> **new InkAnnotation**(`options`): [`InkAnnotation`](InkAnnotation.md)
**`Experimental`**
#### Parameters
• **options**: [`InkAnnotationOptions`](../interfaces/InkAnnotationOptions.md)
Options used to initialize annotation.
#### Returns
[`InkAnnotation`](InkAnnotation.md)
#### Overrides
[`DrawingAnnotation`](DrawingAnnotation.md).[`constructor`](DrawingAnnotation.md#constructors)
## Properties
### stroke
> **stroke**: [`Stroke`](../../Drawing/classes/Stroke.md)
**`Experimental`**
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`stroke`](DrawingAnnotation.md#stroke)
## Accessors
### \_\_annotation
> `get` **\_\_annotation**(): `MarkupAnnotation`
**`Experimental`**
> `set` **\_\_annotation**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: `MarkupAnnotation`
#### Returns
`MarkupAnnotation`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`__annotation`](DrawingAnnotation.md#__annotation)
***
### author
> `get` **author**(): `string`
**`Experimental`**
The author.
> `set` **author**(`author`): `void`
**`Experimental`**
#### Parameters
• **author**: `string`
#### Returns
`string`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`author`](DrawingAnnotation.md#author)
***
### blendMode
> `get` **blendMode**(): [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
**`Experimental`**
blend mode
> `set` **blendMode**(`blendMode`): `void`
**`Experimental`**
#### Parameters
• **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
#### Returns
[`BlendMode`](../../Drawing/enumerations/BlendMode.md)
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`blendMode`](DrawingAnnotation.md#blendmode)
***
### boundingBox
> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
**`Experimental`**
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
> `set` **boundingBox**(`rectangle`): `void`
**`Experimental`**
#### Parameters
• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Returns
[`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`boundingBox`](DrawingAnnotation.md#boundingbox)
***
### content
> `get` **content**(): `string`
**`Experimental`**
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
> `set` **content**(`content`): `void`
**`Experimental`**
#### Parameters
• **content**: `string`
#### Returns
`string`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`content`](DrawingAnnotation.md#content)
***
### creationDate
> `get` **creationDate**(): `Date`
**`Experimental`**
The date and time when the annotation was created.
This property retrieves the creation date from the annotation
and converts it to a JavaScript Date object.
#### Returns
`Date`
The creation date as a JavaScript Date object, or `null` if no
creation date is available in the annotation.
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`creationDate`](DrawingAnnotation.md#creationdate)
***
### dateModified
> `get` **dateModified**(): `Date`
**`Experimental`**
The date and time when the annotation was most recently modified.
> `set` **dateModified**(`date`): `void`
**`Experimental`**
#### Parameters
• **date**: `Date`
#### Returns
`Date`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`dateModified`](DrawingAnnotation.md#datemodified)
***
### hasChanges
> `get` **hasChanges**(): `boolean`
**`Experimental`**
Indicates if the annotation has been changed since the document was opened
#### Returns
`boolean`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`hasChanges`](DrawingAnnotation.md#haschanges)
***
### hidden
> `get` **hidden**(): `boolean`
**`Experimental`**
If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user.
> `set` **hidden**(`hidden`): `void`
**`Experimental`**
#### Parameters
• **hidden**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`hidden`](DrawingAnnotation.md#hidden)
***
### id
> `get` **id**(): `void`
**`Experimental`**
A unique identifier for the annotation.
#### Returns
`void`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`id`](DrawingAnnotation.md#id)
***
### interactive
> `get` **interactive**(): `boolean`
**`Experimental`**
Specifies whether the annotation allows user interaction.
> `set` **interactive**(`interactive`): `void`
**`Experimental`**
#### Parameters
• **interactive**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`interactive`](DrawingAnnotation.md#interactive)
***
### isAdded
> `get` **isAdded**(): `boolean`
**`Experimental`**
Indicates whether the annotation was added to a page
#### Returns
`boolean`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`isAdded`](DrawingAnnotation.md#isadded)
***
### isMaintainingAspectRatio
> `get` **isMaintainingAspectRatio**(): `boolean`
**`Experimental`**
Indicates if the annotation is maintaining its aspect ratio
#### Returns
`boolean`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`isMaintainingAspectRatio`](DrawingAnnotation.md#ismaintainingaspectratio)
***
### isMarkupAnnotation
> `get` **isMarkupAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a markup annotation
#### Returns
`boolean`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`isMarkupAnnotation`](DrawingAnnotation.md#ismarkupannotation)
***
### isModified
> `get` **isModified**(): `boolean`
**`Experimental`**
Indicates if the annotation has changes that have not yet been saved to
the document
#### Returns
`boolean`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`isModified`](DrawingAnnotation.md#ismodified)
***
### isMoveable
> `get` **isMoveable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be moved by the user
#### Returns
`boolean`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`isMoveable`](DrawingAnnotation.md#ismoveable)
***
### isResizable
> `get` **isResizable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be resized by the user
#### Returns
`boolean`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`isResizable`](DrawingAnnotation.md#isresizable)
***
### isRotatable
> `get` **isRotatable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be rotated by the user
#### Returns
`boolean`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`isRotatable`](DrawingAnnotation.md#isrotatable)
***
### isSelectable
> `get` **isSelectable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be selected by the user
#### Returns
`boolean`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`isSelectable`](DrawingAnnotation.md#isselectable)
***
### isWidgetAnnotation
> `get` **isWidgetAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a widget annotation
#### Returns
`boolean`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`isWidgetAnnotation`](DrawingAnnotation.md#iswidgetannotation)
***
### locked
> `get` **locked**(): [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
**`Experimental`**
Represents the locked state of the annotation.
> `set` **locked**(`locked`): `void`
**`Experimental`**
#### Parameters
• **locked**: [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
#### Returns
[`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`locked`](DrawingAnnotation.md#locked)
***
### modificationDate
> `get` **modificationDate**(): `Date`
**`Experimental`**
The date and time when the annotation was last modified.
This property will retrieve the modification date from the annotation
and convert it to a JavaScript Date object.
#### Returns
`Date`
The modification date as a JavaScript Date object, or `null` if no
modification date is available in the annotation.
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`modificationDate`](DrawingAnnotation.md#modificationdate)
***
### opacity
> `get` **opacity**(): `number`
**`Experimental`**
Annotation opacity
> `set` **opacity**(`opacity`): `void`
**`Experimental`**
#### Parameters
• **opacity**: `number`
#### Returns
`number`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`opacity`](DrawingAnnotation.md#opacity)
***
### page
> `get` **page**(): [`Page`](../../../classes/Page.md)
**`Experimental`**
Page in which the annotation is embedded.
> `set` **page**(`page`): `void`
**`Experimental`**
Set the page in which the annotation is embedded.
#### Parameters
• **page**: [`Page`](../../../classes/Page.md)
The page to set as the annotation's page.
#### Returns
[`Page`](../../../classes/Page.md)
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`page`](DrawingAnnotation.md#page)
***
### pageNumber
> `get` **pageNumber**(): `number`
**`Experimental`**
Number of the page in which the annotation is embedded.
#### Returns
`number`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`pageNumber`](DrawingAnnotation.md#pagenumber)
***
### privateData
> `get` **privateData**(): `object`
**`Experimental`**
Custom data to be stored with the annotation
> `set` **privateData**(`privateData`): `void`
**`Experimental`**
#### Parameters
• **privateData**: `object`
#### Returns
`object`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`privateData`](DrawingAnnotation.md#privatedata)
***
### renderProperties
> `get` **renderProperties**(): [`AnnotationRenderProperties`](AnnotationRenderProperties.md)
**`Experimental`**
Object which encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its visibility, interactivity, and other rendering behaviors.
> `set` **renderProperties**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: [`AnnotationRenderProperties`](AnnotationRenderProperties.md)
#### Returns
[`AnnotationRenderProperties`](AnnotationRenderProperties.md)
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`renderProperties`](DrawingAnnotation.md#renderproperties)
***
### source
> `get` **source**(): `void`
**`Experimental`**
Tag that identifies the source the annotation is coming from, if
the source is an input PDF or an input FDF.
Newly created annotations always return `null`.
#### Returns
`void`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`source`](DrawingAnnotation.md#source)
***
### subject
> `get` **subject**(): `string`
**`Experimental`**
The subject.
> `set` **subject**(`subject`): `void`
**`Experimental`**
#### Parameters
• **subject**: `string`
#### Returns
`string`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`subject`](DrawingAnnotation.md#subject)
***
### type
> `get` **type**(): [`AnnotationType`](../enumerations/AnnotationType.md)
**`Experimental`**
The PDF annotation type
#### Returns
[`AnnotationType`](../enumerations/AnnotationType.md)
#### Overrides
[`DrawingAnnotation`](DrawingAnnotation.md).[`type`](DrawingAnnotation.md#type)
## Methods
### dispose()
> **dispose**(): `void`
**`Experimental`**
#### Returns
`void`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`dispose`](DrawingAnnotation.md#dispose)
---
## Class: InternalLinkAnnotation
**`Experimental`**
An InternalLink annotation
## Extends
- [`Annotation`](Annotation.md)
## Constructors
### new InternalLinkAnnotation()
> **new InternalLinkAnnotation**(`options`): [`InternalLinkAnnotation`](InternalLinkAnnotation.md)
**`Experimental`**
#### Parameters
• **options**: [`InternalLinkAnnotationOptions`](../interfaces/InternalLinkAnnotationOptions.md)
Options used to initialize annotation.
#### Returns
[`InternalLinkAnnotation`](InternalLinkAnnotation.md)
#### Overrides
[`Annotation`](Annotation.md).[`constructor`](Annotation.md#constructors)
## Accessors
### \_\_annotation
> `get` **\_\_annotation**(): `InternalLinkAnnotation`
**`Experimental`**
> `set` **\_\_annotation**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: `InternalLinkAnnotation`
#### Returns
`InternalLinkAnnotation`
#### Overrides
[`Annotation`](Annotation.md).[`__annotation`](Annotation.md#__annotation)
***
### boundingBox
> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
**`Experimental`**
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
> `set` **boundingBox**(`rectangle`): `void`
**`Experimental`**
#### Parameters
• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Returns
[`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Inherited from
[`Annotation`](Annotation.md).[`boundingBox`](Annotation.md#boundingbox)
***
### content
> `get` **content**(): `string`
**`Experimental`**
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
> `set` **content**(`content`): `void`
**`Experimental`**
#### Parameters
• **content**: `string`
#### Returns
`string`
#### Inherited from
[`Annotation`](Annotation.md).[`content`](Annotation.md#content)
***
### dateModified
> `get` **dateModified**(): `Date`
**`Experimental`**
The date and time when the annotation was most recently modified.
> `set` **dateModified**(`date`): `void`
**`Experimental`**
#### Parameters
• **date**: `Date`
#### Returns
`Date`
#### Inherited from
[`Annotation`](Annotation.md).[`dateModified`](Annotation.md#datemodified)
***
### destination
> `get` **destination**(): [`Destination`](../../../interfaces/Destination.md)
**`Experimental`**
Gets the destination of the InternalLink annotation.
The destination represents the target location within the PDF document
that the internal link will navigate to when activated.
#### Returns
[`Destination`](../../../interfaces/Destination.md)
***
### hasChanges
> `get` **hasChanges**(): `boolean`
**`Experimental`**
Indicates if the annotation has been changed since the document was opened
#### Returns
`boolean`
#### Inherited from
[`Annotation`](Annotation.md).[`hasChanges`](Annotation.md#haschanges)
***
### hidden
> `get` **hidden**(): `boolean`
**`Experimental`**
If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user.
> `set` **hidden**(`hidden`): `void`
**`Experimental`**
#### Parameters
• **hidden**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`Annotation`](Annotation.md).[`hidden`](Annotation.md#hidden)
***
### id
> `get` **id**(): `void`
**`Experimental`**
A unique identifier for the annotation.
#### Returns
`void`
#### Inherited from
[`Annotation`](Annotation.md).[`id`](Annotation.md#id)
***
### interactive
> `get` **interactive**(): `boolean`
**`Experimental`**
Specifies whether the annotation allows user interaction.
> `set` **interactive**(`interactive`): `void`
**`Experimental`**
#### Parameters
• **interactive**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`Annotation`](Annotation.md).[`interactive`](Annotation.md#interactive)
***
### isAdded
> `get` **isAdded**(): `boolean`
**`Experimental`**
Indicates whether the annotation was added to a page
#### Returns
`boolean`
#### Inherited from
[`Annotation`](Annotation.md).[`isAdded`](Annotation.md#isadded)
***
### isMaintainingAspectRatio
> `get` **isMaintainingAspectRatio**(): `boolean`
**`Experimental`**
Indicates if the annotation is maintaining its aspect ratio
#### Returns
`boolean`
#### Overrides
[`Annotation`](Annotation.md).[`isMaintainingAspectRatio`](Annotation.md#ismaintainingaspectratio)
***
### isMarkupAnnotation
> `get` **isMarkupAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a markup annotation
#### Returns
`boolean`
#### Overrides
[`Annotation`](Annotation.md).[`isMarkupAnnotation`](Annotation.md#ismarkupannotation)
***
### isModified
> `get` **isModified**(): `boolean`
**`Experimental`**
Indicates if the annotation has changes that have not yet been saved to
the document
#### Returns
`boolean`
#### Inherited from
[`Annotation`](Annotation.md).[`isModified`](Annotation.md#ismodified)
***
### isMoveable
> `get` **isMoveable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be moved by the user
#### Returns
`boolean`
#### Overrides
[`Annotation`](Annotation.md).[`isMoveable`](Annotation.md#ismoveable)
***
### isResizable
> `get` **isResizable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be resized by the user
#### Returns
`boolean`
#### Overrides
[`Annotation`](Annotation.md).[`isResizable`](Annotation.md#isresizable)
***
### isRotatable
> `get` **isRotatable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be rotated by the user
#### Returns
`boolean`
#### Overrides
[`Annotation`](Annotation.md).[`isRotatable`](Annotation.md#isrotatable)
***
### isSelectable
> `get` **isSelectable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be selected by the user
#### Returns
`boolean`
#### Overrides
[`Annotation`](Annotation.md).[`isSelectable`](Annotation.md#isselectable)
***
### isWidgetAnnotation
> `get` **isWidgetAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a widget annotation
#### Returns
`boolean`
#### Overrides
[`Annotation`](Annotation.md).[`isWidgetAnnotation`](Annotation.md#iswidgetannotation)
***
### locked
> `get` **locked**(): [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
**`Experimental`**
Represents the locked state of the annotation.
> `set` **locked**(`locked`): `void`
**`Experimental`**
#### Parameters
• **locked**: [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
#### Returns
[`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
#### Inherited from
[`Annotation`](Annotation.md).[`locked`](Annotation.md#locked)
***
### page
> `get` **page**(): [`Page`](../../../classes/Page.md)
**`Experimental`**
Page in which the annotation is embedded.
> `set` **page**(`page`): `void`
**`Experimental`**
Set the page in which the annotation is embedded.
#### Parameters
• **page**: [`Page`](../../../classes/Page.md)
The page to set as the annotation's page.
#### Returns
[`Page`](../../../classes/Page.md)
#### Inherited from
[`Annotation`](Annotation.md).[`page`](Annotation.md#page)
***
### pageNumber
> `get` **pageNumber**(): `number`
**`Experimental`**
Number of the page in which the annotation is embedded.
#### Returns
`number`
#### Inherited from
[`Annotation`](Annotation.md).[`pageNumber`](Annotation.md#pagenumber)
***
### privateData
> `get` **privateData**(): `object`
**`Experimental`**
Custom data to be stored with the annotation
> `set` **privateData**(`privateData`): `void`
**`Experimental`**
#### Parameters
• **privateData**: `object`
#### Returns
`object`
#### Inherited from
[`Annotation`](Annotation.md).[`privateData`](Annotation.md#privatedata)
***
### renderProperties
> `get` **renderProperties**(): [`AnnotationRenderProperties`](AnnotationRenderProperties.md)
**`Experimental`**
Object which encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its visibility, interactivity, and other rendering behaviors.
> `set` **renderProperties**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: [`AnnotationRenderProperties`](AnnotationRenderProperties.md)
#### Returns
[`AnnotationRenderProperties`](AnnotationRenderProperties.md)
#### Inherited from
[`Annotation`](Annotation.md).[`renderProperties`](Annotation.md#renderproperties)
***
### source
> `get` **source**(): `void`
**`Experimental`**
Tag that identifies the source the annotation is coming from, if
the source is an input PDF or an input FDF.
Newly created annotations always return `null`.
#### Returns
`void`
#### Inherited from
[`Annotation`](Annotation.md).[`source`](Annotation.md#source)
***
### type
> `get` **type**(): [`AnnotationType`](../enumerations/AnnotationType.md)
**`Experimental`**
The PDF annotation type
#### Returns
[`AnnotationType`](../enumerations/AnnotationType.md)
#### Overrides
[`Annotation`](Annotation.md).[`type`](Annotation.md#type)
## Methods
### dispose()
> **dispose**(): `void`
**`Experimental`**
#### Returns
`void`
#### Inherited from
[`Annotation`](Annotation.md).[`dispose`](Annotation.md#dispose)
---
## Class: LineAnnotation
**`Experimental`**
A line annotation
## Extends
- [`DrawingAnnotation`](DrawingAnnotation.md)
## Constructors
### new LineAnnotation()
> **new LineAnnotation**(`options`): [`LineAnnotation`](LineAnnotation.md)
**`Experimental`**
#### Parameters
• **options**: [`LineAnnotationOptions`](../interfaces/LineAnnotationOptions.md)
Options used to initialize annotation.
#### Returns
[`LineAnnotation`](LineAnnotation.md)
#### Overrides
[`DrawingAnnotation`](DrawingAnnotation.md).[`constructor`](DrawingAnnotation.md#constructors)
## Properties
### stroke
> **stroke**: [`Stroke`](../../Drawing/classes/Stroke.md)
**`Experimental`**
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`stroke`](DrawingAnnotation.md#stroke)
## Accessors
### \_\_annotation
> `get` **\_\_annotation**(): `MarkupAnnotation`
**`Experimental`**
> `set` **\_\_annotation**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: `MarkupAnnotation`
#### Returns
`MarkupAnnotation`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`__annotation`](DrawingAnnotation.md#__annotation)
***
### author
> `get` **author**(): `string`
**`Experimental`**
The author.
> `set` **author**(`author`): `void`
**`Experimental`**
#### Parameters
• **author**: `string`
#### Returns
`string`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`author`](DrawingAnnotation.md#author)
***
### blendMode
> `get` **blendMode**(): [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
**`Experimental`**
blend mode
> `set` **blendMode**(`blendMode`): `void`
**`Experimental`**
#### Parameters
• **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
#### Returns
[`BlendMode`](../../Drawing/enumerations/BlendMode.md)
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`blendMode`](DrawingAnnotation.md#blendmode)
***
### boundingBox
> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
**`Experimental`**
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
> `set` **boundingBox**(`rectangle`): `void`
**`Experimental`**
#### Parameters
• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Returns
[`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`boundingBox`](DrawingAnnotation.md#boundingbox)
***
### color
> `get` **color**(): [`RgbaColor`](../../Drawing/classes/RgbaColor.md)
**`Experimental`**
Gets the color of the line annotation.
> `set` **color**(`value`): `void`
**`Experimental`**
Sets the color of the line annotation.
#### Parameters
• **value**: [`RgbaColor`](../../Drawing/classes/RgbaColor.md)
#### Returns
[`RgbaColor`](../../Drawing/classes/RgbaColor.md)
***
### content
> `get` **content**(): `string`
**`Experimental`**
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
> `set` **content**(`content`): `void`
**`Experimental`**
#### Parameters
• **content**: `string`
#### Returns
`string`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`content`](DrawingAnnotation.md#content)
***
### creationDate
> `get` **creationDate**(): `Date`
**`Experimental`**
The date and time when the annotation was created.
This property retrieves the creation date from the annotation
and converts it to a JavaScript Date object.
#### Returns
`Date`
The creation date as a JavaScript Date object, or `null` if no
creation date is available in the annotation.
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`creationDate`](DrawingAnnotation.md#creationdate)
***
### dateModified
> `get` **dateModified**(): `Date`
**`Experimental`**
The date and time when the annotation was most recently modified.
> `set` **dateModified**(`date`): `void`
**`Experimental`**
#### Parameters
• **date**: `Date`
#### Returns
`Date`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`dateModified`](DrawingAnnotation.md#datemodified)
***
### endPoint
> `get` **endPoint**(): `PdfPoint`
**`Experimental`**
Gets the end point of the line annotation.
> `set` **endPoint**(`value`): `void`
**`Experimental`**
Sets the end point of the line annotation.
#### Parameters
• **value**: `PdfPoint`
#### Returns
`PdfPoint`
***
### hasChanges
> `get` **hasChanges**(): `boolean`
**`Experimental`**
Indicates if the annotation has been changed since the document was opened
#### Returns
`boolean`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`hasChanges`](DrawingAnnotation.md#haschanges)
***
### hidden
> `get` **hidden**(): `boolean`
**`Experimental`**
If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user.
> `set` **hidden**(`hidden`): `void`
**`Experimental`**
#### Parameters
• **hidden**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`hidden`](DrawingAnnotation.md#hidden)
***
### id
> `get` **id**(): `void`
**`Experimental`**
A unique identifier for the annotation.
#### Returns
`void`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`id`](DrawingAnnotation.md#id)
***
### interactive
> `get` **interactive**(): `boolean`
**`Experimental`**
Specifies whether the annotation allows user interaction.
> `set` **interactive**(`interactive`): `void`
**`Experimental`**
#### Parameters
• **interactive**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`interactive`](DrawingAnnotation.md#interactive)
***
### isAdded
> `get` **isAdded**(): `boolean`
**`Experimental`**
Indicates whether the annotation was added to a page
#### Returns
`boolean`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`isAdded`](DrawingAnnotation.md#isadded)
***
### isMaintainingAspectRatio
> `get` **isMaintainingAspectRatio**(): `boolean`
**`Experimental`**
Indicates if the annotation is maintaining its aspect ratio
#### Returns
`boolean`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`isMaintainingAspectRatio`](DrawingAnnotation.md#ismaintainingaspectratio)
***
### isMarkupAnnotation
> `get` **isMarkupAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a markup annotation
#### Returns
`boolean`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`isMarkupAnnotation`](DrawingAnnotation.md#ismarkupannotation)
***
### isModified
> `get` **isModified**(): `boolean`
**`Experimental`**
Indicates if the annotation has changes that have not yet been saved to
the document
#### Returns
`boolean`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`isModified`](DrawingAnnotation.md#ismodified)
***
### isMoveable
> `get` **isMoveable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be moved by the user
#### Returns
`boolean`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`isMoveable`](DrawingAnnotation.md#ismoveable)
***
### isResizable
> `get` **isResizable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be resized by the user
#### Returns
`boolean`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`isResizable`](DrawingAnnotation.md#isresizable)
***
### isRotatable
> `get` **isRotatable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be rotated by the user
#### Returns
`boolean`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`isRotatable`](DrawingAnnotation.md#isrotatable)
***
### isSelectable
> `get` **isSelectable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be selected by the user
#### Returns
`boolean`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`isSelectable`](DrawingAnnotation.md#isselectable)
***
### isWidgetAnnotation
> `get` **isWidgetAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a widget annotation
#### Returns
`boolean`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`isWidgetAnnotation`](DrawingAnnotation.md#iswidgetannotation)
***
### lineEndingAtEnd
> `get` **lineEndingAtEnd**(): [`LineEnding`](../../Drawing/enumerations/LineEnding.md)
**`Experimental`**
Gets the line ending at the end of the line annotation.
> `set` **lineEndingAtEnd**(`value`): `void`
**`Experimental`**
Sets the line ending at the end of the line annotation.
#### Parameters
• **value**: [`LineEnding`](../../Drawing/enumerations/LineEnding.md)
#### Returns
[`LineEnding`](../../Drawing/enumerations/LineEnding.md)
***
### lineEndingAtStart
> `get` **lineEndingAtStart**(): [`LineEnding`](../../Drawing/enumerations/LineEnding.md)
**`Experimental`**
Gets the line ending at the start of the line annotation.
> `set` **lineEndingAtStart**(`value`): `void`
**`Experimental`**
Sets the line ending at the start of the line annotation.
#### Parameters
• **value**: [`LineEnding`](../../Drawing/enumerations/LineEnding.md)
#### Returns
[`LineEnding`](../../Drawing/enumerations/LineEnding.md)
***
### lineWidth
> `get` **lineWidth**(): `number`
**`Experimental`**
Gets the line width of the line annotation.
> `set` **lineWidth**(`value`): `void`
**`Experimental`**
Sets the line width of the line annotation.
#### Parameters
• **value**: `number`
#### Returns
`number`
***
### locked
> `get` **locked**(): [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
**`Experimental`**
Represents the locked state of the annotation.
> `set` **locked**(`locked`): `void`
**`Experimental`**
#### Parameters
• **locked**: [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
#### Returns
[`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`locked`](DrawingAnnotation.md#locked)
***
### modificationDate
> `get` **modificationDate**(): `Date`
**`Experimental`**
The date and time when the annotation was last modified.
This property will retrieve the modification date from the annotation
and convert it to a JavaScript Date object.
#### Returns
`Date`
The modification date as a JavaScript Date object, or `null` if no
modification date is available in the annotation.
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`modificationDate`](DrawingAnnotation.md#modificationdate)
***
### opacity
> `get` **opacity**(): `number`
**`Experimental`**
Annotation opacity
> `set` **opacity**(`opacity`): `void`
**`Experimental`**
#### Parameters
• **opacity**: `number`
#### Returns
`number`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`opacity`](DrawingAnnotation.md#opacity)
***
### page
> `get` **page**(): [`Page`](../../../classes/Page.md)
**`Experimental`**
Page in which the annotation is embedded.
> `set` **page**(`page`): `void`
**`Experimental`**
Set the page in which the annotation is embedded.
#### Parameters
• **page**: [`Page`](../../../classes/Page.md)
The page to set as the annotation's page.
#### Returns
[`Page`](../../../classes/Page.md)
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`page`](DrawingAnnotation.md#page)
***
### pageNumber
> `get` **pageNumber**(): `number`
**`Experimental`**
Number of the page in which the annotation is embedded.
#### Returns
`number`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`pageNumber`](DrawingAnnotation.md#pagenumber)
***
### privateData
> `get` **privateData**(): `object`
**`Experimental`**
Custom data to be stored with the annotation
> `set` **privateData**(`privateData`): `void`
**`Experimental`**
#### Parameters
• **privateData**: `object`
#### Returns
`object`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`privateData`](DrawingAnnotation.md#privatedata)
***
### renderProperties
> `get` **renderProperties**(): [`AnnotationRenderProperties`](AnnotationRenderProperties.md)
**`Experimental`**
Object which encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its visibility, interactivity, and other rendering behaviors.
> `set` **renderProperties**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: [`AnnotationRenderProperties`](AnnotationRenderProperties.md)
#### Returns
[`AnnotationRenderProperties`](AnnotationRenderProperties.md)
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`renderProperties`](DrawingAnnotation.md#renderproperties)
***
### source
> `get` **source**(): `void`
**`Experimental`**
Tag that identifies the source the annotation is coming from, if
the source is an input PDF or an input FDF.
Newly created annotations always return `null`.
#### Returns
`void`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`source`](DrawingAnnotation.md#source)
***
### startPoint
> `get` **startPoint**(): `PdfPoint`
**`Experimental`**
Gets the start point of the line annotation.
> `set` **startPoint**(`value`): `void`
**`Experimental`**
Sets the start point of the line annotation.
#### Parameters
• **value**: `PdfPoint`
#### Returns
`PdfPoint`
***
### subject
> `get` **subject**(): `string`
**`Experimental`**
The subject.
> `set` **subject**(`subject`): `void`
**`Experimental`**
#### Parameters
• **subject**: `string`
#### Returns
`string`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`subject`](DrawingAnnotation.md#subject)
***
### type
> `get` **type**(): [`AnnotationType`](../enumerations/AnnotationType.md)
**`Experimental`**
The PDF annotation type
#### Returns
[`AnnotationType`](../enumerations/AnnotationType.md)
#### Overrides
[`DrawingAnnotation`](DrawingAnnotation.md).[`type`](DrawingAnnotation.md#type)
## Methods
### dispose()
> **dispose**(): `void`
**`Experimental`**
#### Returns
`void`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`dispose`](DrawingAnnotation.md#dispose)
---
## Class: LinkAnnotation
**`Experimental`**
A link annotation
## Extends
- [`Annotation`](Annotation.md)
## Constructors
### new LinkAnnotation()
> **new LinkAnnotation**(`options`): [`LinkAnnotation`](LinkAnnotation.md)
**`Experimental`**
#### Parameters
• **options**: [`LinkAnnotationOptions`](../interfaces/LinkAnnotationOptions.md)
Options used to initialize annotation.
#### Returns
[`LinkAnnotation`](LinkAnnotation.md)
#### Overrides
[`Annotation`](Annotation.md).[`constructor`](Annotation.md#constructors)
## Properties
### action
> **action**: [`Action`](../../Actions/classes/Action.md)
**`Experimental`**
The action that is performed when the link annotation is clicked on
## Accessors
### \_\_annotation
> `get` **\_\_annotation**(): `Annotation`
**`Experimental`**
> `set` **\_\_annotation**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: `Annotation`
#### Returns
`Annotation`
#### Inherited from
[`Annotation`](Annotation.md).[`__annotation`](Annotation.md#__annotation)
***
### boundingBox
> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
**`Experimental`**
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
> `set` **boundingBox**(`rectangle`): `void`
**`Experimental`**
#### Parameters
• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Returns
[`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Inherited from
[`Annotation`](Annotation.md).[`boundingBox`](Annotation.md#boundingbox)
***
### content
> `get` **content**(): `string`
**`Experimental`**
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
> `set` **content**(`content`): `void`
**`Experimental`**
#### Parameters
• **content**: `string`
#### Returns
`string`
#### Inherited from
[`Annotation`](Annotation.md).[`content`](Annotation.md#content)
***
### dateModified
> `get` **dateModified**(): `Date`
**`Experimental`**
The date and time when the annotation was most recently modified.
> `set` **dateModified**(`date`): `void`
**`Experimental`**
#### Parameters
• **date**: `Date`
#### Returns
`Date`
#### Inherited from
[`Annotation`](Annotation.md).[`dateModified`](Annotation.md#datemodified)
***
### hasChanges
> `get` **hasChanges**(): `boolean`
**`Experimental`**
Indicates if the annotation has been changed since the document was opened
#### Returns
`boolean`
#### Inherited from
[`Annotation`](Annotation.md).[`hasChanges`](Annotation.md#haschanges)
***
### hidden
> `get` **hidden**(): `boolean`
**`Experimental`**
If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user.
> `set` **hidden**(`hidden`): `void`
**`Experimental`**
#### Parameters
• **hidden**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`Annotation`](Annotation.md).[`hidden`](Annotation.md#hidden)
***
### id
> `get` **id**(): `void`
**`Experimental`**
A unique identifier for the annotation.
#### Returns
`void`
#### Inherited from
[`Annotation`](Annotation.md).[`id`](Annotation.md#id)
***
### interactive
> `get` **interactive**(): `boolean`
**`Experimental`**
Specifies whether the annotation allows user interaction.
> `set` **interactive**(`interactive`): `void`
**`Experimental`**
#### Parameters
• **interactive**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`Annotation`](Annotation.md).[`interactive`](Annotation.md#interactive)
***
### isAdded
> `get` **isAdded**(): `boolean`
**`Experimental`**
Indicates whether the annotation was added to a page
#### Returns
`boolean`
#### Inherited from
[`Annotation`](Annotation.md).[`isAdded`](Annotation.md#isadded)
***
### isMaintainingAspectRatio
> `get` **isMaintainingAspectRatio**(): `boolean`
**`Experimental`**
Indicates if the annotation is maintaining its aspect ratio
#### Returns
`boolean`
#### Overrides
[`Annotation`](Annotation.md).[`isMaintainingAspectRatio`](Annotation.md#ismaintainingaspectratio)
***
### isMarkupAnnotation
> `get` **isMarkupAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a markup annotation
#### Returns
`boolean`
#### Overrides
[`Annotation`](Annotation.md).[`isMarkupAnnotation`](Annotation.md#ismarkupannotation)
***
### isModified
> `get` **isModified**(): `boolean`
**`Experimental`**
Indicates if the annotation has changes that have not yet been saved to
the document
#### Returns
`boolean`
#### Inherited from
[`Annotation`](Annotation.md).[`isModified`](Annotation.md#ismodified)
***
### isMoveable
> `get` **isMoveable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be moved by the user
#### Returns
`boolean`
#### Overrides
[`Annotation`](Annotation.md).[`isMoveable`](Annotation.md#ismoveable)
***
### isResizable
> `get` **isResizable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be resized by the user
#### Returns
`boolean`
#### Overrides
[`Annotation`](Annotation.md).[`isResizable`](Annotation.md#isresizable)
***
### isRotatable
> `get` **isRotatable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be rotated by the user
#### Returns
`boolean`
#### Overrides
[`Annotation`](Annotation.md).[`isRotatable`](Annotation.md#isrotatable)
***
### isSelectable
> `get` **isSelectable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be selected by the user
#### Returns
`boolean`
#### Overrides
[`Annotation`](Annotation.md).[`isSelectable`](Annotation.md#isselectable)
***
### isWidgetAnnotation
> `get` **isWidgetAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a widget annotation
#### Returns
`boolean`
#### Overrides
[`Annotation`](Annotation.md).[`isWidgetAnnotation`](Annotation.md#iswidgetannotation)
***
### locked
> `get` **locked**(): [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
**`Experimental`**
Represents the locked state of the annotation.
> `set` **locked**(`locked`): `void`
**`Experimental`**
#### Parameters
• **locked**: [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
#### Returns
[`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
#### Inherited from
[`Annotation`](Annotation.md).[`locked`](Annotation.md#locked)
***
### page
> `get` **page**(): [`Page`](../../../classes/Page.md)
**`Experimental`**
Page in which the annotation is embedded.
> `set` **page**(`page`): `void`
**`Experimental`**
Set the page in which the annotation is embedded.
#### Parameters
• **page**: [`Page`](../../../classes/Page.md)
The page to set as the annotation's page.
#### Returns
[`Page`](../../../classes/Page.md)
#### Inherited from
[`Annotation`](Annotation.md).[`page`](Annotation.md#page)
***
### pageNumber
> `get` **pageNumber**(): `number`
**`Experimental`**
Number of the page in which the annotation is embedded.
#### Returns
`number`
#### Inherited from
[`Annotation`](Annotation.md).[`pageNumber`](Annotation.md#pagenumber)
***
### privateData
> `get` **privateData**(): `object`
**`Experimental`**
Custom data to be stored with the annotation
> `set` **privateData**(`privateData`): `void`
**`Experimental`**
#### Parameters
• **privateData**: `object`
#### Returns
`object`
#### Inherited from
[`Annotation`](Annotation.md).[`privateData`](Annotation.md#privatedata)
***
### renderProperties
> `get` **renderProperties**(): [`AnnotationRenderProperties`](AnnotationRenderProperties.md)
**`Experimental`**
Object which encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its visibility, interactivity, and other rendering behaviors.
> `set` **renderProperties**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: [`AnnotationRenderProperties`](AnnotationRenderProperties.md)
#### Returns
[`AnnotationRenderProperties`](AnnotationRenderProperties.md)
#### Inherited from
[`Annotation`](Annotation.md).[`renderProperties`](Annotation.md#renderproperties)
***
### source
> `get` **source**(): `void`
**`Experimental`**
Tag that identifies the source the annotation is coming from, if
the source is an input PDF or an input FDF.
Newly created annotations always return `null`.
#### Returns
`void`
#### Inherited from
[`Annotation`](Annotation.md).[`source`](Annotation.md#source)
***
### type
> `get` **type**(): [`AnnotationType`](../enumerations/AnnotationType.md)
**`Experimental`**
The PDF annotation type
#### Default Value
`AnnotationType.Link`
#### Returns
[`AnnotationType`](../enumerations/AnnotationType.md)
#### Overrides
[`Annotation`](Annotation.md).[`type`](Annotation.md#type)
## Methods
### dispose()
> **dispose**(): `void`
**`Experimental`**
#### Returns
`void`
#### Inherited from
[`Annotation`](Annotation.md).[`dispose`](Annotation.md#dispose)
---
## Class: `abstract` MarkupAnnotation
Base class for all markup annotations
## Extends
- [`Annotation`](Annotation.md)
## Extended by
- [`CaretAnnotation`](CaretAnnotation.md)
- [`DrawingAnnotation`](DrawingAnnotation.md)
- [`FileAttachmentAnnotation`](FileAttachmentAnnotation.md)
- [`FreeTextAnnotation`](FreeTextAnnotation.md)
- [`NoteAnnotation`](NoteAnnotation.md)
- [`StampAnnotation`](StampAnnotation.md)
- [`TextMarkupAnnotation`](TextMarkupAnnotation.md)
## Constructors
### new MarkupAnnotation()
> **new MarkupAnnotation**(`options`): [`MarkupAnnotation`](MarkupAnnotation.md)
#### Parameters
• **options**: [`MarkupAnnotationOptions`](../interfaces/MarkupAnnotationOptions.md)
#### Returns
[`MarkupAnnotation`](MarkupAnnotation.md)
#### Overrides
[`Annotation`](Annotation.md).[`constructor`](Annotation.md#constructors)
## Accessors
### \_\_annotation
> `get` **\_\_annotation**(): `MarkupAnnotation`
> `set` **\_\_annotation**(`v`): `void`
#### Parameters
• **v**: `MarkupAnnotation`
#### Returns
`MarkupAnnotation`
#### Overrides
[`Annotation`](Annotation.md).[`__annotation`](Annotation.md#__annotation)
***
### author
> `get` **author**(): `string`
The author.
> `set` **author**(`author`): `void`
#### Parameters
• **author**: `string`
#### Returns
`string`
***
### blendMode
> `get` **blendMode**(): [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
**`Experimental`**
blend mode
> `set` **blendMode**(`blendMode`): `void`
#### Parameters
• **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
#### Returns
[`BlendMode`](../../Drawing/enumerations/BlendMode.md)
***
### boundingBox
> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
> `set` **boundingBox**(`rectangle`): `void`
#### Parameters
• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Returns
[`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Inherited from
[`Annotation`](Annotation.md).[`boundingBox`](Annotation.md#boundingbox)
***
### content
> `get` **content**(): `string`
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
> `set` **content**(`content`): `void`
#### Parameters
• **content**: `string`
#### Returns
`string`
#### Inherited from
[`Annotation`](Annotation.md).[`content`](Annotation.md#content)
***
### creationDate
> `get` **creationDate**(): `Date`
The date and time when the annotation was created.
This property retrieves the creation date from the annotation
and converts it to a JavaScript Date object.
#### Returns
`Date`
The creation date as a JavaScript Date object, or `null` if no
creation date is available in the annotation.
***
### dateModified
> `get` **dateModified**(): `Date`
**`Experimental`**
The date and time when the annotation was most recently modified.
> `set` **dateModified**(`date`): `void`
#### Parameters
• **date**: `Date`
#### Returns
`Date`
#### Inherited from
[`Annotation`](Annotation.md).[`dateModified`](Annotation.md#datemodified)
***
### hasChanges
> `get` **hasChanges**(): `boolean`
**`Experimental`**
Indicates if the annotation has been changed since the document was opened
#### Returns
`boolean`
#### Inherited from
[`Annotation`](Annotation.md).[`hasChanges`](Annotation.md#haschanges)
***
### hidden
> `get` **hidden**(): `boolean`
If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user.
> `set` **hidden**(`hidden`): `void`
#### Parameters
• **hidden**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`Annotation`](Annotation.md).[`hidden`](Annotation.md#hidden)
***
### id
> `get` **id**(): `void`
**`Experimental`**
A unique identifier for the annotation.
#### Returns
`void`
#### Inherited from
[`Annotation`](Annotation.md).[`id`](Annotation.md#id)
***
### interactive
> `get` **interactive**(): `boolean`
Specifies whether the annotation allows user interaction.
> `set` **interactive**(`interactive`): `void`
#### Parameters
• **interactive**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`Annotation`](Annotation.md).[`interactive`](Annotation.md#interactive)
***
### isAdded
> `get` **isAdded**(): `boolean`
**`Experimental`**
Indicates whether the annotation was added to a page
#### Returns
`boolean`
#### Inherited from
[`Annotation`](Annotation.md).[`isAdded`](Annotation.md#isadded)
***
### isMaintainingAspectRatio
> `get` `abstract` **isMaintainingAspectRatio**(): `boolean`
Indicates if the annotation is maintaining its aspect ratio
#### Returns
`boolean`
#### Inherited from
[`Annotation`](Annotation.md).[`isMaintainingAspectRatio`](Annotation.md#ismaintainingaspectratio)
***
### isMarkupAnnotation
> `get` **isMarkupAnnotation**(): `boolean`
Indicates if the annotation is a markup annotation
#### Returns
`boolean`
#### Overrides
[`Annotation`](Annotation.md).[`isMarkupAnnotation`](Annotation.md#ismarkupannotation)
***
### isModified
> `get` **isModified**(): `boolean`
**`Experimental`**
Indicates if the annotation has changes that have not yet been saved to
the document
#### Returns
`boolean`
#### Inherited from
[`Annotation`](Annotation.md).[`isModified`](Annotation.md#ismodified)
***
### isMoveable
> `get` `abstract` **isMoveable**(): `boolean`
Indicates if the annotation can be moved by the user
#### Returns
`boolean`
#### Inherited from
[`Annotation`](Annotation.md).[`isMoveable`](Annotation.md#ismoveable)
***
### isResizable
> `get` `abstract` **isResizable**(): `boolean`
Indicates if the annotation can be resized by the user
#### Returns
`boolean`
#### Inherited from
[`Annotation`](Annotation.md).[`isResizable`](Annotation.md#isresizable)
***
### isRotatable
> `get` `abstract` **isRotatable**(): `boolean`
Indicates if the annotation can be rotated by the user
#### Returns
`boolean`
#### Inherited from
[`Annotation`](Annotation.md).[`isRotatable`](Annotation.md#isrotatable)
***
### isSelectable
> `get` `abstract` **isSelectable**(): `boolean`
Indicates if the annotation can be selected by the user
#### Returns
`boolean`
#### Inherited from
[`Annotation`](Annotation.md).[`isSelectable`](Annotation.md#isselectable)
***
### isWidgetAnnotation
> `get` **isWidgetAnnotation**(): `boolean`
Indicates if the annotation is a widget annotation
#### Returns
`boolean`
#### Overrides
[`Annotation`](Annotation.md).[`isWidgetAnnotation`](Annotation.md#iswidgetannotation)
***
### locked
> `get` **locked**(): [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
Represents the locked state of the annotation.
> `set` **locked**(`locked`): `void`
#### Parameters
• **locked**: [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
#### Returns
[`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
#### Inherited from
[`Annotation`](Annotation.md).[`locked`](Annotation.md#locked)
***
### modificationDate
> `get` **modificationDate**(): `Date`
The date and time when the annotation was last modified.
This property will retrieve the modification date from the annotation
and convert it to a JavaScript Date object.
#### Returns
`Date`
The modification date as a JavaScript Date object, or `null` if no
modification date is available in the annotation.
***
### opacity
> `get` **opacity**(): `number`
**`Experimental`**
Annotation opacity
> `set` **opacity**(`opacity`): `void`
#### Parameters
• **opacity**: `number`
#### Returns
`number`
***
### page
> `get` **page**(): [`Page`](../../../classes/Page.md)
Page in which the annotation is embedded.
> `set` **page**(`page`): `void`
Set the page in which the annotation is embedded.
#### Parameters
• **page**: [`Page`](../../../classes/Page.md)
The page to set as the annotation's page.
#### Returns
[`Page`](../../../classes/Page.md)
#### Inherited from
[`Annotation`](Annotation.md).[`page`](Annotation.md#page)
***
### pageNumber
> `get` **pageNumber**(): `number`
**`Experimental`**
Number of the page in which the annotation is embedded.
#### Returns
`number`
#### Inherited from
[`Annotation`](Annotation.md).[`pageNumber`](Annotation.md#pagenumber)
***
### privateData
> `get` **privateData**(): `object`
**`Experimental`**
Custom data to be stored with the annotation
> `set` **privateData**(`privateData`): `void`
#### Parameters
• **privateData**: `object`
#### Returns
`object`
#### Inherited from
[`Annotation`](Annotation.md).[`privateData`](Annotation.md#privatedata)
***
### renderProperties
> `get` **renderProperties**(): [`AnnotationRenderProperties`](AnnotationRenderProperties.md)
Object which encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its visibility, interactivity, and other rendering behaviors.
> `set` **renderProperties**(`v`): `void`
#### Parameters
• **v**: [`AnnotationRenderProperties`](AnnotationRenderProperties.md)
#### Returns
[`AnnotationRenderProperties`](AnnotationRenderProperties.md)
#### Inherited from
[`Annotation`](Annotation.md).[`renderProperties`](Annotation.md#renderproperties)
***
### source
> `get` **source**(): `void`
**`Experimental`**
Tag that identifies the source the annotation is coming from, if
the source is an input PDF or an input FDF.
Newly created annotations always return `null`.
#### Returns
`void`
#### Inherited from
[`Annotation`](Annotation.md).[`source`](Annotation.md#source)
***
### subject
> `get` **subject**(): `string`
The subject.
> `set` **subject**(`subject`): `void`
#### Parameters
• **subject**: `string`
#### Returns
`string`
***
### type
> `get` `abstract` **type**(): [`AnnotationType`](../enumerations/AnnotationType.md)
The PDF annotation type
#### Returns
[`AnnotationType`](../enumerations/AnnotationType.md)
#### Inherited from
[`Annotation`](Annotation.md).[`type`](Annotation.md#type)
## Methods
### dispose()
> **dispose**(): `void`
Disposes of the object, releasing any resources it holds.
The `dispose` method is responsible for performing cleanup operations and releasing
any resources acquired by the object. Once an object is disposed, it should not
be used, and attempts to do so may result in undefined behavior.
#### Returns
`void`
#### Inherited from
[`Annotation`](Annotation.md).[`dispose`](Annotation.md#dispose)
---
## Class: NoteAnnotation
**`Experimental`**
A sticky note annotation
## Extends
- [`MarkupAnnotation`](MarkupAnnotation.md)
## Constructors
### new NoteAnnotation()
> **new NoteAnnotation**(`options`): [`NoteAnnotation`](NoteAnnotation.md)
**`Experimental`**
#### Parameters
• **options**: [`NoteAnnotationOptions`](../interfaces/NoteAnnotationOptions.md)
Options used to initialize annotation.
#### Returns
[`NoteAnnotation`](NoteAnnotation.md)
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`constructor`](MarkupAnnotation.md#constructors)
## Properties
### icon
> **icon**: [`NoteAnnotationIcon`](../enumerations/NoteAnnotationIcon.md)
**`Experimental`**
Icon to be displayed
## Accessors
### \_\_annotation
> `get` **\_\_annotation**(): `StickyNoteAnnotation`
**`Experimental`**
> `set` **\_\_annotation**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: `StickyNoteAnnotation`
#### Returns
`StickyNoteAnnotation`
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`__annotation`](MarkupAnnotation.md#__annotation)
***
### author
> `get` **author**(): `string`
**`Experimental`**
The author.
> `set` **author**(`author`): `void`
**`Experimental`**
#### Parameters
• **author**: `string`
#### Returns
`string`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`author`](MarkupAnnotation.md#author)
***
### blendMode
> `get` **blendMode**(): [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
**`Experimental`**
blend mode
> `set` **blendMode**(`blendMode`): `void`
**`Experimental`**
#### Parameters
• **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
#### Returns
[`BlendMode`](../../Drawing/enumerations/BlendMode.md)
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`blendMode`](MarkupAnnotation.md#blendmode)
***
### boundingBox
> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
**`Experimental`**
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
> `set` **boundingBox**(`rectangle`): `void`
**`Experimental`**
#### Parameters
• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Returns
[`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`boundingBox`](MarkupAnnotation.md#boundingbox)
***
### content
> `get` **content**(): `string`
**`Experimental`**
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
> `set` **content**(`content`): `void`
**`Experimental`**
#### Parameters
• **content**: `string`
#### Returns
`string`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`content`](MarkupAnnotation.md#content)
***
### creationDate
> `get` **creationDate**(): `Date`
**`Experimental`**
The date and time when the annotation was created.
This property retrieves the creation date from the annotation
and converts it to a JavaScript Date object.
#### Returns
`Date`
The creation date as a JavaScript Date object, or `null` if no
creation date is available in the annotation.
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`creationDate`](MarkupAnnotation.md#creationdate)
***
### dateModified
> `get` **dateModified**(): `Date`
**`Experimental`**
The date and time when the annotation was most recently modified.
> `set` **dateModified**(`date`): `void`
**`Experimental`**
#### Parameters
• **date**: `Date`
#### Returns
`Date`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`dateModified`](MarkupAnnotation.md#datemodified)
***
### fillColor
> `get` **fillColor**(): `NoteAnnotationColor`
**`Experimental`**
Represents the fill color of the annotation in hexadecimal representation.
> `set` **fillColor**(`fillColor`): `void`
**`Experimental`**
#### Parameters
• **fillColor**: `NoteAnnotationColor`
#### Returns
`NoteAnnotationColor`
***
### hasChanges
> `get` **hasChanges**(): `boolean`
**`Experimental`**
Indicates if the annotation has been changed since the document was opened
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`hasChanges`](MarkupAnnotation.md#haschanges)
***
### hidden
> `get` **hidden**(): `boolean`
**`Experimental`**
If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user.
> `set` **hidden**(`hidden`): `void`
**`Experimental`**
#### Parameters
• **hidden**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`hidden`](MarkupAnnotation.md#hidden)
***
### id
> `get` **id**(): `void`
**`Experimental`**
A unique identifier for the annotation.
#### Returns
`void`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`id`](MarkupAnnotation.md#id)
***
### interactive
> `get` **interactive**(): `boolean`
**`Experimental`**
Specifies whether the annotation allows user interaction.
> `set` **interactive**(`interactive`): `void`
**`Experimental`**
#### Parameters
• **interactive**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`interactive`](MarkupAnnotation.md#interactive)
***
### isAdded
> `get` **isAdded**(): `boolean`
**`Experimental`**
Indicates whether the annotation was added to a page
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`isAdded`](MarkupAnnotation.md#isadded)
***
### isMaintainingAspectRatio
> `get` **isMaintainingAspectRatio**(): `boolean`
**`Experimental`**
Indicates if the annotation is maintaining its aspect ratio
#### Returns
`boolean`
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`isMaintainingAspectRatio`](MarkupAnnotation.md#ismaintainingaspectratio)
***
### isMarkupAnnotation
> `get` **isMarkupAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a markup annotation
#### Returns
`boolean`
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`isMarkupAnnotation`](MarkupAnnotation.md#ismarkupannotation)
***
### isModified
> `get` **isModified**(): `boolean`
**`Experimental`**
Indicates if the annotation has changes that have not yet been saved to
the document
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`isModified`](MarkupAnnotation.md#ismodified)
***
### isMoveable
> `get` **isMoveable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be moved by the user
#### Returns
`boolean`
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`isMoveable`](MarkupAnnotation.md#ismoveable)
***
### isResizable
> `get` **isResizable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be resized by the user
#### Returns
`boolean`
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`isResizable`](MarkupAnnotation.md#isresizable)
***
### isRotatable
> `get` **isRotatable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be rotated by the user
#### Returns
`boolean`
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`isRotatable`](MarkupAnnotation.md#isrotatable)
***
### isSelectable
> `get` **isSelectable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be selected by the user
#### Returns
`boolean`
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`isSelectable`](MarkupAnnotation.md#isselectable)
***
### isWidgetAnnotation
> `get` **isWidgetAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a widget annotation
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`isWidgetAnnotation`](MarkupAnnotation.md#iswidgetannotation)
***
### locked
> `get` **locked**(): [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
**`Experimental`**
Represents the locked state of the annotation.
> `set` **locked**(`locked`): `void`
**`Experimental`**
#### Parameters
• **locked**: [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
#### Returns
[`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`locked`](MarkupAnnotation.md#locked)
***
### modificationDate
> `get` **modificationDate**(): `Date`
**`Experimental`**
The date and time when the annotation was last modified.
This property will retrieve the modification date from the annotation
and convert it to a JavaScript Date object.
#### Returns
`Date`
The modification date as a JavaScript Date object, or `null` if no
modification date is available in the annotation.
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`modificationDate`](MarkupAnnotation.md#modificationdate)
***
### opacity
> `get` **opacity**(): `number`
**`Experimental`**
Annotation opacity
> `set` **opacity**(`opacity`): `void`
**`Experimental`**
#### Parameters
• **opacity**: `number`
#### Returns
`number`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`opacity`](MarkupAnnotation.md#opacity)
***
### page
> `get` **page**(): [`Page`](../../../classes/Page.md)
**`Experimental`**
Page in which the annotation is embedded.
> `set` **page**(`page`): `void`
**`Experimental`**
Set the page in which the annotation is embedded.
#### Parameters
• **page**: [`Page`](../../../classes/Page.md)
The page to set as the annotation's page.
#### Returns
[`Page`](../../../classes/Page.md)
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`page`](MarkupAnnotation.md#page)
***
### pageNumber
> `get` **pageNumber**(): `number`
**`Experimental`**
Number of the page in which the annotation is embedded.
#### Returns
`number`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`pageNumber`](MarkupAnnotation.md#pagenumber)
***
### privateData
> `get` **privateData**(): `object`
**`Experimental`**
Custom data to be stored with the annotation
> `set` **privateData**(`privateData`): `void`
**`Experimental`**
#### Parameters
• **privateData**: `object`
#### Returns
`object`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`privateData`](MarkupAnnotation.md#privatedata)
***
### renderProperties
> `get` **renderProperties**(): [`AnnotationRenderProperties`](AnnotationRenderProperties.md)
**`Experimental`**
Object which encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its visibility, interactivity, and other rendering behaviors.
> `set` **renderProperties**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: [`AnnotationRenderProperties`](AnnotationRenderProperties.md)
#### Returns
[`AnnotationRenderProperties`](AnnotationRenderProperties.md)
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`renderProperties`](MarkupAnnotation.md#renderproperties)
***
### source
> `get` **source**(): `void`
**`Experimental`**
Tag that identifies the source the annotation is coming from, if
the source is an input PDF or an input FDF.
Newly created annotations always return `null`.
#### Returns
`void`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`source`](MarkupAnnotation.md#source)
***
### subject
> `get` **subject**(): `string`
**`Experimental`**
The subject.
> `set` **subject**(`subject`): `void`
**`Experimental`**
#### Parameters
• **subject**: `string`
#### Returns
`string`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`subject`](MarkupAnnotation.md#subject)
***
### topLeft
> `get` **topLeft**(): `PdfPoint`
**`Experimental`**
Represents the top left point of the annotation on the page, specified as a `PdfPoint`.
> `set` **topLeft**(`topLeft`): `void`
**`Experimental`**
#### Parameters
• **topLeft**: `PdfPoint`
#### Returns
`PdfPoint`
***
### type
> `get` **type**(): [`AnnotationType`](../enumerations/AnnotationType.md)
**`Experimental`**
The PDF annotation type
#### Returns
[`AnnotationType`](../enumerations/AnnotationType.md)
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`type`](MarkupAnnotation.md#type)
## Methods
### dispose()
> **dispose**(): `void`
**`Experimental`**
#### Returns
`void`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`dispose`](MarkupAnnotation.md#dispose)
---
## Class: PolyLineAnnotation
**`Experimental`**
A poly line annotation
## Extends
- [`DrawingAnnotation`](DrawingAnnotation.md)
## Constructors
### new PolyLineAnnotation()
> **new PolyLineAnnotation**(`options`): [`PolyLineAnnotation`](PolyLineAnnotation.md)
**`Experimental`**
#### Parameters
• **options**: [`PolyLineAnnotationOptions`](../interfaces/PolyLineAnnotationOptions.md)
Options used to initialize annotation.
#### Returns
[`PolyLineAnnotation`](PolyLineAnnotation.md)
#### Overrides
[`DrawingAnnotation`](DrawingAnnotation.md).[`constructor`](DrawingAnnotation.md#constructors)
## Properties
### stroke
> **stroke**: [`Stroke`](../../Drawing/classes/Stroke.md)
**`Experimental`**
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`stroke`](DrawingAnnotation.md#stroke)
## Accessors
### \_\_annotation
> `get` **\_\_annotation**(): `MarkupAnnotation`
**`Experimental`**
> `set` **\_\_annotation**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: `MarkupAnnotation`
#### Returns
`MarkupAnnotation`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`__annotation`](DrawingAnnotation.md#__annotation)
***
### author
> `get` **author**(): `string`
**`Experimental`**
The author.
> `set` **author**(`author`): `void`
**`Experimental`**
#### Parameters
• **author**: `string`
#### Returns
`string`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`author`](DrawingAnnotation.md#author)
***
### blendMode
> `get` **blendMode**(): [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
**`Experimental`**
blend mode
> `set` **blendMode**(`blendMode`): `void`
**`Experimental`**
#### Parameters
• **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
#### Returns
[`BlendMode`](../../Drawing/enumerations/BlendMode.md)
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`blendMode`](DrawingAnnotation.md#blendmode)
***
### boundingBox
> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
**`Experimental`**
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
> `set` **boundingBox**(`rectangle`): `void`
**`Experimental`**
#### Parameters
• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Returns
[`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`boundingBox`](DrawingAnnotation.md#boundingbox)
***
### content
> `get` **content**(): `string`
**`Experimental`**
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
> `set` **content**(`content`): `void`
**`Experimental`**
#### Parameters
• **content**: `string`
#### Returns
`string`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`content`](DrawingAnnotation.md#content)
***
### creationDate
> `get` **creationDate**(): `Date`
**`Experimental`**
The date and time when the annotation was created.
This property retrieves the creation date from the annotation
and converts it to a JavaScript Date object.
#### Returns
`Date`
The creation date as a JavaScript Date object, or `null` if no
creation date is available in the annotation.
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`creationDate`](DrawingAnnotation.md#creationdate)
***
### dateModified
> `get` **dateModified**(): `Date`
**`Experimental`**
The date and time when the annotation was most recently modified.
> `set` **dateModified**(`date`): `void`
**`Experimental`**
#### Parameters
• **date**: `Date`
#### Returns
`Date`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`dateModified`](DrawingAnnotation.md#datemodified)
***
### hasChanges
> `get` **hasChanges**(): `boolean`
**`Experimental`**
Indicates if the annotation has been changed since the document was opened
#### Returns
`boolean`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`hasChanges`](DrawingAnnotation.md#haschanges)
***
### hidden
> `get` **hidden**(): `boolean`
**`Experimental`**
If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user.
> `set` **hidden**(`hidden`): `void`
**`Experimental`**
#### Parameters
• **hidden**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`hidden`](DrawingAnnotation.md#hidden)
***
### id
> `get` **id**(): `void`
**`Experimental`**
A unique identifier for the annotation.
#### Returns
`void`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`id`](DrawingAnnotation.md#id)
***
### interactive
> `get` **interactive**(): `boolean`
**`Experimental`**
Specifies whether the annotation allows user interaction.
> `set` **interactive**(`interactive`): `void`
**`Experimental`**
#### Parameters
• **interactive**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`interactive`](DrawingAnnotation.md#interactive)
***
### isAdded
> `get` **isAdded**(): `boolean`
**`Experimental`**
Indicates whether the annotation was added to a page
#### Returns
`boolean`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`isAdded`](DrawingAnnotation.md#isadded)
***
### isMaintainingAspectRatio
> `get` **isMaintainingAspectRatio**(): `boolean`
**`Experimental`**
Indicates if the annotation is maintaining its aspect ratio
#### Returns
`boolean`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`isMaintainingAspectRatio`](DrawingAnnotation.md#ismaintainingaspectratio)
***
### isMarkupAnnotation
> `get` **isMarkupAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a markup annotation
#### Returns
`boolean`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`isMarkupAnnotation`](DrawingAnnotation.md#ismarkupannotation)
***
### isModified
> `get` **isModified**(): `boolean`
**`Experimental`**
Indicates if the annotation has changes that have not yet been saved to
the document
#### Returns
`boolean`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`isModified`](DrawingAnnotation.md#ismodified)
***
### isMoveable
> `get` **isMoveable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be moved by the user
#### Returns
`boolean`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`isMoveable`](DrawingAnnotation.md#ismoveable)
***
### isResizable
> `get` **isResizable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be resized by the user
#### Returns
`boolean`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`isResizable`](DrawingAnnotation.md#isresizable)
***
### isRotatable
> `get` **isRotatable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be rotated by the user
#### Returns
`boolean`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`isRotatable`](DrawingAnnotation.md#isrotatable)
***
### isSelectable
> `get` **isSelectable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be selected by the user
#### Returns
`boolean`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`isSelectable`](DrawingAnnotation.md#isselectable)
***
### isWidgetAnnotation
> `get` **isWidgetAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a widget annotation
#### Returns
`boolean`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`isWidgetAnnotation`](DrawingAnnotation.md#iswidgetannotation)
***
### locked
> `get` **locked**(): [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
**`Experimental`**
Represents the locked state of the annotation.
> `set` **locked**(`locked`): `void`
**`Experimental`**
#### Parameters
• **locked**: [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
#### Returns
[`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`locked`](DrawingAnnotation.md#locked)
***
### modificationDate
> `get` **modificationDate**(): `Date`
**`Experimental`**
The date and time when the annotation was last modified.
This property will retrieve the modification date from the annotation
and convert it to a JavaScript Date object.
#### Returns
`Date`
The modification date as a JavaScript Date object, or `null` if no
modification date is available in the annotation.
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`modificationDate`](DrawingAnnotation.md#modificationdate)
***
### opacity
> `get` **opacity**(): `number`
**`Experimental`**
Annotation opacity
> `set` **opacity**(`opacity`): `void`
**`Experimental`**
#### Parameters
• **opacity**: `number`
#### Returns
`number`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`opacity`](DrawingAnnotation.md#opacity)
***
### page
> `get` **page**(): [`Page`](../../../classes/Page.md)
**`Experimental`**
Page in which the annotation is embedded.
> `set` **page**(`page`): `void`
**`Experimental`**
Set the page in which the annotation is embedded.
#### Parameters
• **page**: [`Page`](../../../classes/Page.md)
The page to set as the annotation's page.
#### Returns
[`Page`](../../../classes/Page.md)
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`page`](DrawingAnnotation.md#page)
***
### pageNumber
> `get` **pageNumber**(): `number`
**`Experimental`**
Number of the page in which the annotation is embedded.
#### Returns
`number`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`pageNumber`](DrawingAnnotation.md#pagenumber)
***
### privateData
> `get` **privateData**(): `object`
**`Experimental`**
Custom data to be stored with the annotation
> `set` **privateData**(`privateData`): `void`
**`Experimental`**
#### Parameters
• **privateData**: `object`
#### Returns
`object`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`privateData`](DrawingAnnotation.md#privatedata)
***
### renderProperties
> `get` **renderProperties**(): [`AnnotationRenderProperties`](AnnotationRenderProperties.md)
**`Experimental`**
Object which encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its visibility, interactivity, and other rendering behaviors.
> `set` **renderProperties**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: [`AnnotationRenderProperties`](AnnotationRenderProperties.md)
#### Returns
[`AnnotationRenderProperties`](AnnotationRenderProperties.md)
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`renderProperties`](DrawingAnnotation.md#renderproperties)
***
### source
> `get` **source**(): `void`
**`Experimental`**
Tag that identifies the source the annotation is coming from, if
the source is an input PDF or an input FDF.
Newly created annotations always return `null`.
#### Returns
`void`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`source`](DrawingAnnotation.md#source)
***
### subject
> `get` **subject**(): `string`
**`Experimental`**
The subject.
> `set` **subject**(`subject`): `void`
**`Experimental`**
#### Parameters
• **subject**: `string`
#### Returns
`string`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`subject`](DrawingAnnotation.md#subject)
***
### type
> `get` **type**(): [`AnnotationType`](../enumerations/AnnotationType.md)
**`Experimental`**
The PDF annotation type
#### Returns
[`AnnotationType`](../enumerations/AnnotationType.md)
#### Overrides
[`DrawingAnnotation`](DrawingAnnotation.md).[`type`](DrawingAnnotation.md#type)
## Methods
### dispose()
> **dispose**(): `void`
**`Experimental`**
#### Returns
`void`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`dispose`](DrawingAnnotation.md#dispose)
---
## Class: PolygonAnnotation
**`Experimental`**
An polygon drawing annotation
## Extends
- [`ShapeAnnotation`](ShapeAnnotation.md)
## Constructors
### new PolygonAnnotation()
> **new PolygonAnnotation**(`options`): [`PolygonAnnotation`](PolygonAnnotation.md)
**`Experimental`**
#### Parameters
• **options**: [`PolygonAnnotationOptions`](../interfaces/PolygonAnnotationOptions.md)
Options used to initialize annotation.
#### Returns
[`PolygonAnnotation`](PolygonAnnotation.md)
#### Overrides
[`ShapeAnnotation`](ShapeAnnotation.md).[`constructor`](ShapeAnnotation.md#constructors)
## Properties
### stroke
> **stroke**: [`Stroke`](../../Drawing/classes/Stroke.md)
**`Experimental`**
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`stroke`](ShapeAnnotation.md#stroke)
## Accessors
### \_\_annotation
> `get` **\_\_annotation**(): `MarkupAnnotation`
**`Experimental`**
> `set` **\_\_annotation**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: `MarkupAnnotation`
#### Returns
`MarkupAnnotation`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`__annotation`](ShapeAnnotation.md#__annotation)
***
### author
> `get` **author**(): `string`
**`Experimental`**
The author.
> `set` **author**(`author`): `void`
**`Experimental`**
#### Parameters
• **author**: `string`
#### Returns
`string`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`author`](ShapeAnnotation.md#author)
***
### blendMode
> `get` **blendMode**(): [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
**`Experimental`**
blend mode
> `set` **blendMode**(`blendMode`): `void`
**`Experimental`**
#### Parameters
• **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
#### Returns
[`BlendMode`](../../Drawing/enumerations/BlendMode.md)
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`blendMode`](ShapeAnnotation.md#blendmode)
***
### boundingBox
> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
**`Experimental`**
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
> `set` **boundingBox**(`rectangle`): `void`
**`Experimental`**
#### Parameters
• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Returns
[`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`boundingBox`](ShapeAnnotation.md#boundingbox)
***
### content
> `get` **content**(): `string`
**`Experimental`**
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
> `set` **content**(`content`): `void`
**`Experimental`**
#### Parameters
• **content**: `string`
#### Returns
`string`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`content`](ShapeAnnotation.md#content)
***
### creationDate
> `get` **creationDate**(): `Date`
**`Experimental`**
The date and time when the annotation was created.
This property retrieves the creation date from the annotation
and converts it to a JavaScript Date object.
#### Returns
`Date`
The creation date as a JavaScript Date object, or `null` if no
creation date is available in the annotation.
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`creationDate`](ShapeAnnotation.md#creationdate)
***
### dateModified
> `get` **dateModified**(): `Date`
**`Experimental`**
The date and time when the annotation was most recently modified.
> `set` **dateModified**(`date`): `void`
**`Experimental`**
#### Parameters
• **date**: `Date`
#### Returns
`Date`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`dateModified`](ShapeAnnotation.md#datemodified)
***
### hasChanges
> `get` **hasChanges**(): `boolean`
**`Experimental`**
Indicates if the annotation has been changed since the document was opened
#### Returns
`boolean`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`hasChanges`](ShapeAnnotation.md#haschanges)
***
### hidden
> `get` **hidden**(): `boolean`
**`Experimental`**
If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user.
> `set` **hidden**(`hidden`): `void`
**`Experimental`**
#### Parameters
• **hidden**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`hidden`](ShapeAnnotation.md#hidden)
***
### id
> `get` **id**(): `void`
**`Experimental`**
A unique identifier for the annotation.
#### Returns
`void`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`id`](ShapeAnnotation.md#id)
***
### interactive
> `get` **interactive**(): `boolean`
**`Experimental`**
Specifies whether the annotation allows user interaction.
> `set` **interactive**(`interactive`): `void`
**`Experimental`**
#### Parameters
• **interactive**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`interactive`](ShapeAnnotation.md#interactive)
***
### isAdded
> `get` **isAdded**(): `boolean`
**`Experimental`**
Indicates whether the annotation was added to a page
#### Returns
`boolean`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`isAdded`](ShapeAnnotation.md#isadded)
***
### isMaintainingAspectRatio
> `get` **isMaintainingAspectRatio**(): `boolean`
**`Experimental`**
Indicates if the annotation is maintaining its aspect ratio
#### Returns
`boolean`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`isMaintainingAspectRatio`](ShapeAnnotation.md#ismaintainingaspectratio)
***
### isMarkupAnnotation
> `get` **isMarkupAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a markup annotation
#### Returns
`boolean`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`isMarkupAnnotation`](ShapeAnnotation.md#ismarkupannotation)
***
### isModified
> `get` **isModified**(): `boolean`
**`Experimental`**
Indicates if the annotation has changes that have not yet been saved to
the document
#### Returns
`boolean`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`isModified`](ShapeAnnotation.md#ismodified)
***
### isMoveable
> `get` **isMoveable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be moved by the user
#### Returns
`boolean`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`isMoveable`](ShapeAnnotation.md#ismoveable)
***
### isResizable
> `get` **isResizable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be resized by the user
#### Returns
`boolean`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`isResizable`](ShapeAnnotation.md#isresizable)
***
### isRotatable
> `get` **isRotatable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be rotated by the user
#### Returns
`boolean`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`isRotatable`](ShapeAnnotation.md#isrotatable)
***
### isSelectable
> `get` **isSelectable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be selected by the user
#### Returns
`boolean`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`isSelectable`](ShapeAnnotation.md#isselectable)
***
### isWidgetAnnotation
> `get` **isWidgetAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a widget annotation
#### Returns
`boolean`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`isWidgetAnnotation`](ShapeAnnotation.md#iswidgetannotation)
***
### locked
> `get` **locked**(): [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
**`Experimental`**
Represents the locked state of the annotation.
> `set` **locked**(`locked`): `void`
**`Experimental`**
#### Parameters
• **locked**: [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
#### Returns
[`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`locked`](ShapeAnnotation.md#locked)
***
### modificationDate
> `get` **modificationDate**(): `Date`
**`Experimental`**
The date and time when the annotation was last modified.
This property will retrieve the modification date from the annotation
and convert it to a JavaScript Date object.
#### Returns
`Date`
The modification date as a JavaScript Date object, or `null` if no
modification date is available in the annotation.
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`modificationDate`](ShapeAnnotation.md#modificationdate)
***
### opacity
> `get` **opacity**(): `number`
**`Experimental`**
Annotation opacity
> `set` **opacity**(`opacity`): `void`
**`Experimental`**
#### Parameters
• **opacity**: `number`
#### Returns
`number`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`opacity`](ShapeAnnotation.md#opacity)
***
### page
> `get` **page**(): [`Page`](../../../classes/Page.md)
**`Experimental`**
Page in which the annotation is embedded.
> `set` **page**(`page`): `void`
**`Experimental`**
Set the page in which the annotation is embedded.
#### Parameters
• **page**: [`Page`](../../../classes/Page.md)
The page to set as the annotation's page.
#### Returns
[`Page`](../../../classes/Page.md)
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`page`](ShapeAnnotation.md#page)
***
### pageNumber
> `get` **pageNumber**(): `number`
**`Experimental`**
Number of the page in which the annotation is embedded.
#### Returns
`number`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`pageNumber`](ShapeAnnotation.md#pagenumber)
***
### privateData
> `get` **privateData**(): `object`
**`Experimental`**
Custom data to be stored with the annotation
> `set` **privateData**(`privateData`): `void`
**`Experimental`**
#### Parameters
• **privateData**: `object`
#### Returns
`object`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`privateData`](ShapeAnnotation.md#privatedata)
***
### renderProperties
> `get` **renderProperties**(): [`AnnotationRenderProperties`](AnnotationRenderProperties.md)
**`Experimental`**
Object which encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its visibility, interactivity, and other rendering behaviors.
> `set` **renderProperties**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: [`AnnotationRenderProperties`](AnnotationRenderProperties.md)
#### Returns
[`AnnotationRenderProperties`](AnnotationRenderProperties.md)
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`renderProperties`](ShapeAnnotation.md#renderproperties)
***
### source
> `get` **source**(): `void`
**`Experimental`**
Tag that identifies the source the annotation is coming from, if
the source is an input PDF or an input FDF.
Newly created annotations always return `null`.
#### Returns
`void`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`source`](ShapeAnnotation.md#source)
***
### subject
> `get` **subject**(): `string`
**`Experimental`**
The subject.
> `set` **subject**(`subject`): `void`
**`Experimental`**
#### Parameters
• **subject**: `string`
#### Returns
`string`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`subject`](ShapeAnnotation.md#subject)
***
### type
> `get` **type**(): [`AnnotationType`](../enumerations/AnnotationType.md)
**`Experimental`**
The PDF annotation type
#### Returns
[`AnnotationType`](../enumerations/AnnotationType.md)
#### Overrides
[`ShapeAnnotation`](ShapeAnnotation.md).[`type`](ShapeAnnotation.md#type)
## Methods
### dispose()
> **dispose**(): `void`
**`Experimental`**
#### Returns
`void`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`dispose`](ShapeAnnotation.md#dispose)
---
## Class: RectangleAnnotation
**`Experimental`**
A rectangle drawing annotation
## Extends
- [`ShapeAnnotation`](ShapeAnnotation.md)
## Constructors
### new RectangleAnnotation()
> **new RectangleAnnotation**(`options`): [`RectangleAnnotation`](RectangleAnnotation.md)
**`Experimental`**
#### Parameters
• **options**: [`RectangleAnnotationOptions`](../interfaces/RectangleAnnotationOptions.md)
Options used to initialize annotation.
#### Returns
[`RectangleAnnotation`](RectangleAnnotation.md)
#### Overrides
[`ShapeAnnotation`](ShapeAnnotation.md).[`constructor`](ShapeAnnotation.md#constructors)
## Properties
### stroke
> **stroke**: [`Stroke`](../../Drawing/classes/Stroke.md)
**`Experimental`**
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`stroke`](ShapeAnnotation.md#stroke)
## Accessors
### \_\_annotation
> `get` **\_\_annotation**(): `MarkupAnnotation`
**`Experimental`**
> `set` **\_\_annotation**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: `MarkupAnnotation`
#### Returns
`MarkupAnnotation`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`__annotation`](ShapeAnnotation.md#__annotation)
***
### author
> `get` **author**(): `string`
**`Experimental`**
The author.
> `set` **author**(`author`): `void`
**`Experimental`**
#### Parameters
• **author**: `string`
#### Returns
`string`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`author`](ShapeAnnotation.md#author)
***
### blendMode
> `get` **blendMode**(): [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
**`Experimental`**
blend mode
> `set` **blendMode**(`blendMode`): `void`
**`Experimental`**
#### Parameters
• **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
#### Returns
[`BlendMode`](../../Drawing/enumerations/BlendMode.md)
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`blendMode`](ShapeAnnotation.md#blendmode)
***
### boundingBox
> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
**`Experimental`**
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
> `set` **boundingBox**(`rectangle`): `void`
**`Experimental`**
#### Parameters
• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Returns
[`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`boundingBox`](ShapeAnnotation.md#boundingbox)
***
### content
> `get` **content**(): `string`
**`Experimental`**
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
> `set` **content**(`content`): `void`
**`Experimental`**
#### Parameters
• **content**: `string`
#### Returns
`string`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`content`](ShapeAnnotation.md#content)
***
### creationDate
> `get` **creationDate**(): `Date`
**`Experimental`**
The date and time when the annotation was created.
This property retrieves the creation date from the annotation
and converts it to a JavaScript Date object.
#### Returns
`Date`
The creation date as a JavaScript Date object, or `null` if no
creation date is available in the annotation.
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`creationDate`](ShapeAnnotation.md#creationdate)
***
### dateModified
> `get` **dateModified**(): `Date`
**`Experimental`**
The date and time when the annotation was most recently modified.
> `set` **dateModified**(`date`): `void`
**`Experimental`**
#### Parameters
• **date**: `Date`
#### Returns
`Date`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`dateModified`](ShapeAnnotation.md#datemodified)
***
### hasChanges
> `get` **hasChanges**(): `boolean`
**`Experimental`**
Indicates if the annotation has been changed since the document was opened
#### Returns
`boolean`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`hasChanges`](ShapeAnnotation.md#haschanges)
***
### hidden
> `get` **hidden**(): `boolean`
**`Experimental`**
If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user.
> `set` **hidden**(`hidden`): `void`
**`Experimental`**
#### Parameters
• **hidden**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`hidden`](ShapeAnnotation.md#hidden)
***
### id
> `get` **id**(): `void`
**`Experimental`**
A unique identifier for the annotation.
#### Returns
`void`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`id`](ShapeAnnotation.md#id)
***
### interactive
> `get` **interactive**(): `boolean`
**`Experimental`**
Specifies whether the annotation allows user interaction.
> `set` **interactive**(`interactive`): `void`
**`Experimental`**
#### Parameters
• **interactive**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`interactive`](ShapeAnnotation.md#interactive)
***
### isAdded
> `get` **isAdded**(): `boolean`
**`Experimental`**
Indicates whether the annotation was added to a page
#### Returns
`boolean`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`isAdded`](ShapeAnnotation.md#isadded)
***
### isMaintainingAspectRatio
> `get` **isMaintainingAspectRatio**(): `boolean`
**`Experimental`**
Indicates if the annotation is maintaining its aspect ratio
#### Returns
`boolean`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`isMaintainingAspectRatio`](ShapeAnnotation.md#ismaintainingaspectratio)
***
### isMarkupAnnotation
> `get` **isMarkupAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a markup annotation
#### Returns
`boolean`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`isMarkupAnnotation`](ShapeAnnotation.md#ismarkupannotation)
***
### isModified
> `get` **isModified**(): `boolean`
**`Experimental`**
Indicates if the annotation has changes that have not yet been saved to
the document
#### Returns
`boolean`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`isModified`](ShapeAnnotation.md#ismodified)
***
### isMoveable
> `get` **isMoveable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be moved by the user
#### Returns
`boolean`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`isMoveable`](ShapeAnnotation.md#ismoveable)
***
### isResizable
> `get` **isResizable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be resized by the user
#### Returns
`boolean`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`isResizable`](ShapeAnnotation.md#isresizable)
***
### isRotatable
> `get` **isRotatable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be rotated by the user
#### Returns
`boolean`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`isRotatable`](ShapeAnnotation.md#isrotatable)
***
### isSelectable
> `get` **isSelectable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be selected by the user
#### Returns
`boolean`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`isSelectable`](ShapeAnnotation.md#isselectable)
***
### isWidgetAnnotation
> `get` **isWidgetAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a widget annotation
#### Returns
`boolean`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`isWidgetAnnotation`](ShapeAnnotation.md#iswidgetannotation)
***
### locked
> `get` **locked**(): [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
**`Experimental`**
Represents the locked state of the annotation.
> `set` **locked**(`locked`): `void`
**`Experimental`**
#### Parameters
• **locked**: [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
#### Returns
[`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`locked`](ShapeAnnotation.md#locked)
***
### modificationDate
> `get` **modificationDate**(): `Date`
**`Experimental`**
The date and time when the annotation was last modified.
This property will retrieve the modification date from the annotation
and convert it to a JavaScript Date object.
#### Returns
`Date`
The modification date as a JavaScript Date object, or `null` if no
modification date is available in the annotation.
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`modificationDate`](ShapeAnnotation.md#modificationdate)
***
### opacity
> `get` **opacity**(): `number`
**`Experimental`**
Annotation opacity
> `set` **opacity**(`opacity`): `void`
**`Experimental`**
#### Parameters
• **opacity**: `number`
#### Returns
`number`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`opacity`](ShapeAnnotation.md#opacity)
***
### page
> `get` **page**(): [`Page`](../../../classes/Page.md)
**`Experimental`**
Page in which the annotation is embedded.
> `set` **page**(`page`): `void`
**`Experimental`**
Set the page in which the annotation is embedded.
#### Parameters
• **page**: [`Page`](../../../classes/Page.md)
The page to set as the annotation's page.
#### Returns
[`Page`](../../../classes/Page.md)
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`page`](ShapeAnnotation.md#page)
***
### pageNumber
> `get` **pageNumber**(): `number`
**`Experimental`**
Number of the page in which the annotation is embedded.
#### Returns
`number`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`pageNumber`](ShapeAnnotation.md#pagenumber)
***
### privateData
> `get` **privateData**(): `object`
**`Experimental`**
Custom data to be stored with the annotation
> `set` **privateData**(`privateData`): `void`
**`Experimental`**
#### Parameters
• **privateData**: `object`
#### Returns
`object`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`privateData`](ShapeAnnotation.md#privatedata)
***
### renderProperties
> `get` **renderProperties**(): [`AnnotationRenderProperties`](AnnotationRenderProperties.md)
**`Experimental`**
Object which encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its visibility, interactivity, and other rendering behaviors.
> `set` **renderProperties**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: [`AnnotationRenderProperties`](AnnotationRenderProperties.md)
#### Returns
[`AnnotationRenderProperties`](AnnotationRenderProperties.md)
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`renderProperties`](ShapeAnnotation.md#renderproperties)
***
### source
> `get` **source**(): `void`
**`Experimental`**
Tag that identifies the source the annotation is coming from, if
the source is an input PDF or an input FDF.
Newly created annotations always return `null`.
#### Returns
`void`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`source`](ShapeAnnotation.md#source)
***
### subject
> `get` **subject**(): `string`
**`Experimental`**
The subject.
> `set` **subject**(`subject`): `void`
**`Experimental`**
#### Parameters
• **subject**: `string`
#### Returns
`string`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`subject`](ShapeAnnotation.md#subject)
***
### type
> `get` **type**(): [`AnnotationType`](../enumerations/AnnotationType.md)
**`Experimental`**
The PDF annotation type
#### Returns
[`AnnotationType`](../enumerations/AnnotationType.md)
#### Overrides
[`ShapeAnnotation`](ShapeAnnotation.md).[`type`](ShapeAnnotation.md#type)
## Methods
### dispose()
> **dispose**(): `void`
**`Experimental`**
#### Returns
`void`
#### Inherited from
[`ShapeAnnotation`](ShapeAnnotation.md).[`dispose`](ShapeAnnotation.md#dispose)
---
## Class: `abstract` ShapeAnnotation
**`Experimental`**
Base class for shape annotations
## Extends
- [`DrawingAnnotation`](DrawingAnnotation.md)
## Extended by
- [`EllipseAnnotation`](EllipseAnnotation.md)
- [`PolygonAnnotation`](PolygonAnnotation.md)
- [`RectangleAnnotation`](RectangleAnnotation.md)
## Constructors
### new ShapeAnnotation()
> **new ShapeAnnotation**(`options`): [`ShapeAnnotation`](ShapeAnnotation.md)
**`Experimental`**
#### Parameters
• **options**: [`ShapeAnnotationOptions`](../interfaces/ShapeAnnotationOptions.md)
Options used to initialize annotation.
#### Returns
[`ShapeAnnotation`](ShapeAnnotation.md)
#### Overrides
[`DrawingAnnotation`](DrawingAnnotation.md).[`constructor`](DrawingAnnotation.md#constructors)
## Properties
### stroke
> **stroke**: [`Stroke`](../../Drawing/classes/Stroke.md)
**`Experimental`**
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`stroke`](DrawingAnnotation.md#stroke)
## Accessors
### \_\_annotation
> `get` **\_\_annotation**(): `MarkupAnnotation`
**`Experimental`**
> `set` **\_\_annotation**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: `MarkupAnnotation`
#### Returns
`MarkupAnnotation`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`__annotation`](DrawingAnnotation.md#__annotation)
***
### author
> `get` **author**(): `string`
**`Experimental`**
The author.
> `set` **author**(`author`): `void`
**`Experimental`**
#### Parameters
• **author**: `string`
#### Returns
`string`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`author`](DrawingAnnotation.md#author)
***
### blendMode
> `get` **blendMode**(): [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
**`Experimental`**
blend mode
> `set` **blendMode**(`blendMode`): `void`
**`Experimental`**
#### Parameters
• **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
#### Returns
[`BlendMode`](../../Drawing/enumerations/BlendMode.md)
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`blendMode`](DrawingAnnotation.md#blendmode)
***
### boundingBox
> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
**`Experimental`**
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
> `set` **boundingBox**(`rectangle`): `void`
**`Experimental`**
#### Parameters
• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Returns
[`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`boundingBox`](DrawingAnnotation.md#boundingbox)
***
### content
> `get` **content**(): `string`
**`Experimental`**
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
> `set` **content**(`content`): `void`
**`Experimental`**
#### Parameters
• **content**: `string`
#### Returns
`string`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`content`](DrawingAnnotation.md#content)
***
### creationDate
> `get` **creationDate**(): `Date`
**`Experimental`**
The date and time when the annotation was created.
This property retrieves the creation date from the annotation
and converts it to a JavaScript Date object.
#### Returns
`Date`
The creation date as a JavaScript Date object, or `null` if no
creation date is available in the annotation.
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`creationDate`](DrawingAnnotation.md#creationdate)
***
### dateModified
> `get` **dateModified**(): `Date`
**`Experimental`**
The date and time when the annotation was most recently modified.
> `set` **dateModified**(`date`): `void`
**`Experimental`**
#### Parameters
• **date**: `Date`
#### Returns
`Date`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`dateModified`](DrawingAnnotation.md#datemodified)
***
### hasChanges
> `get` **hasChanges**(): `boolean`
**`Experimental`**
Indicates if the annotation has been changed since the document was opened
#### Returns
`boolean`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`hasChanges`](DrawingAnnotation.md#haschanges)
***
### hidden
> `get` **hidden**(): `boolean`
**`Experimental`**
If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user.
> `set` **hidden**(`hidden`): `void`
**`Experimental`**
#### Parameters
• **hidden**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`hidden`](DrawingAnnotation.md#hidden)
***
### id
> `get` **id**(): `void`
**`Experimental`**
A unique identifier for the annotation.
#### Returns
`void`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`id`](DrawingAnnotation.md#id)
***
### interactive
> `get` **interactive**(): `boolean`
**`Experimental`**
Specifies whether the annotation allows user interaction.
> `set` **interactive**(`interactive`): `void`
**`Experimental`**
#### Parameters
• **interactive**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`interactive`](DrawingAnnotation.md#interactive)
***
### isAdded
> `get` **isAdded**(): `boolean`
**`Experimental`**
Indicates whether the annotation was added to a page
#### Returns
`boolean`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`isAdded`](DrawingAnnotation.md#isadded)
***
### isMaintainingAspectRatio
> `get` **isMaintainingAspectRatio**(): `boolean`
**`Experimental`**
Indicates if the annotation is maintaining its aspect ratio
#### Returns
`boolean`
#### Overrides
[`DrawingAnnotation`](DrawingAnnotation.md).[`isMaintainingAspectRatio`](DrawingAnnotation.md#ismaintainingaspectratio)
***
### isMarkupAnnotation
> `get` **isMarkupAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a markup annotation
#### Returns
`boolean`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`isMarkupAnnotation`](DrawingAnnotation.md#ismarkupannotation)
***
### isModified
> `get` **isModified**(): `boolean`
**`Experimental`**
Indicates if the annotation has changes that have not yet been saved to
the document
#### Returns
`boolean`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`isModified`](DrawingAnnotation.md#ismodified)
***
### isMoveable
> `get` **isMoveable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be moved by the user
#### Returns
`boolean`
#### Overrides
[`DrawingAnnotation`](DrawingAnnotation.md).[`isMoveable`](DrawingAnnotation.md#ismoveable)
***
### isResizable
> `get` **isResizable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be resized by the user
#### Returns
`boolean`
#### Overrides
[`DrawingAnnotation`](DrawingAnnotation.md).[`isResizable`](DrawingAnnotation.md#isresizable)
***
### isRotatable
> `get` **isRotatable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be rotated by the user
#### Returns
`boolean`
#### Overrides
[`DrawingAnnotation`](DrawingAnnotation.md).[`isRotatable`](DrawingAnnotation.md#isrotatable)
***
### isSelectable
> `get` **isSelectable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be selected by the user
#### Returns
`boolean`
#### Overrides
[`DrawingAnnotation`](DrawingAnnotation.md).[`isSelectable`](DrawingAnnotation.md#isselectable)
***
### isWidgetAnnotation
> `get` **isWidgetAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a widget annotation
#### Returns
`boolean`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`isWidgetAnnotation`](DrawingAnnotation.md#iswidgetannotation)
***
### locked
> `get` **locked**(): [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
**`Experimental`**
Represents the locked state of the annotation.
> `set` **locked**(`locked`): `void`
**`Experimental`**
#### Parameters
• **locked**: [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
#### Returns
[`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`locked`](DrawingAnnotation.md#locked)
***
### modificationDate
> `get` **modificationDate**(): `Date`
**`Experimental`**
The date and time when the annotation was last modified.
This property will retrieve the modification date from the annotation
and convert it to a JavaScript Date object.
#### Returns
`Date`
The modification date as a JavaScript Date object, or `null` if no
modification date is available in the annotation.
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`modificationDate`](DrawingAnnotation.md#modificationdate)
***
### opacity
> `get` **opacity**(): `number`
**`Experimental`**
Annotation opacity
> `set` **opacity**(`opacity`): `void`
**`Experimental`**
#### Parameters
• **opacity**: `number`
#### Returns
`number`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`opacity`](DrawingAnnotation.md#opacity)
***
### page
> `get` **page**(): [`Page`](../../../classes/Page.md)
**`Experimental`**
Page in which the annotation is embedded.
> `set` **page**(`page`): `void`
**`Experimental`**
Set the page in which the annotation is embedded.
#### Parameters
• **page**: [`Page`](../../../classes/Page.md)
The page to set as the annotation's page.
#### Returns
[`Page`](../../../classes/Page.md)
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`page`](DrawingAnnotation.md#page)
***
### pageNumber
> `get` **pageNumber**(): `number`
**`Experimental`**
Number of the page in which the annotation is embedded.
#### Returns
`number`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`pageNumber`](DrawingAnnotation.md#pagenumber)
***
### privateData
> `get` **privateData**(): `object`
**`Experimental`**
Custom data to be stored with the annotation
> `set` **privateData**(`privateData`): `void`
**`Experimental`**
#### Parameters
• **privateData**: `object`
#### Returns
`object`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`privateData`](DrawingAnnotation.md#privatedata)
***
### renderProperties
> `get` **renderProperties**(): [`AnnotationRenderProperties`](AnnotationRenderProperties.md)
**`Experimental`**
Object which encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its visibility, interactivity, and other rendering behaviors.
> `set` **renderProperties**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: [`AnnotationRenderProperties`](AnnotationRenderProperties.md)
#### Returns
[`AnnotationRenderProperties`](AnnotationRenderProperties.md)
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`renderProperties`](DrawingAnnotation.md#renderproperties)
***
### source
> `get` **source**(): `void`
**`Experimental`**
Tag that identifies the source the annotation is coming from, if
the source is an input PDF or an input FDF.
Newly created annotations always return `null`.
#### Returns
`void`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`source`](DrawingAnnotation.md#source)
***
### subject
> `get` **subject**(): `string`
**`Experimental`**
The subject.
> `set` **subject**(`subject`): `void`
**`Experimental`**
#### Parameters
• **subject**: `string`
#### Returns
`string`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`subject`](DrawingAnnotation.md#subject)
***
### type
> `get` `abstract` **type**(): [`AnnotationType`](../enumerations/AnnotationType.md)
**`Experimental`**
The PDF annotation type
#### Returns
[`AnnotationType`](../enumerations/AnnotationType.md)
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`type`](DrawingAnnotation.md#type)
## Methods
### dispose()
> **dispose**(): `void`
**`Experimental`**
#### Returns
`void`
#### Inherited from
[`DrawingAnnotation`](DrawingAnnotation.md).[`dispose`](DrawingAnnotation.md#dispose)
---
## Class: StampAnnotation
Base class for all stamp annotations
## Extends
- [`MarkupAnnotation`](MarkupAnnotation.md)
## Constructors
### new StampAnnotation()
> **new StampAnnotation**(`options`): [`StampAnnotation`](StampAnnotation.md)
Creates a new `StampAnnotation` instance.
#### Parameters
• **options**: [`StampAnnotationOptions`](../interfaces/StampAnnotationOptions.md)
Options used to initialize annotation.
#### Returns
[`StampAnnotation`](StampAnnotation.md)
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`constructor`](MarkupAnnotation.md#constructors)
## Accessors
### \_\_annotation
> `get` **\_\_annotation**(): `StampAnnotation`
> `set` **\_\_annotation**(`v`): `void`
#### Parameters
• **v**: `StampAnnotation`
#### Returns
`StampAnnotation`
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`__annotation`](MarkupAnnotation.md#__annotation)
***
### author
> `get` **author**(): `string`
The author.
> `set` **author**(`author`): `void`
#### Parameters
• **author**: `string`
#### Returns
`string`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`author`](MarkupAnnotation.md#author)
***
### blendMode
> `get` **blendMode**(): [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
**`Experimental`**
blend mode
> `set` **blendMode**(`blendMode`): `void`
#### Parameters
• **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
#### Returns
[`BlendMode`](../../Drawing/enumerations/BlendMode.md)
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`blendMode`](MarkupAnnotation.md#blendmode)
***
### boundingBox
> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
> `set` **boundingBox**(`rectangle`): `void`
#### Parameters
• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Returns
[`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`boundingBox`](MarkupAnnotation.md#boundingbox)
***
### content
> `get` **content**(): `string`
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
> `set` **content**(`content`): `void`
#### Parameters
• **content**: `string`
#### Returns
`string`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`content`](MarkupAnnotation.md#content)
***
### creationDate
> `get` **creationDate**(): `Date`
The date and time when the annotation was created.
This property retrieves the creation date from the annotation
and converts it to a JavaScript Date object.
#### Returns
`Date`
The creation date as a JavaScript Date object, or `null` if no
creation date is available in the annotation.
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`creationDate`](MarkupAnnotation.md#creationdate)
***
### data
> `get` **data**(): [`StampData`](../type-aliases/StampData.md)
An object representing the stamp annotation data, which depends on the subtype.
#### Returns
[`StampData`](../type-aliases/StampData.md)
***
### dateModified
> `get` **dateModified**(): `Date`
**`Experimental`**
The date and time when the annotation was most recently modified.
> `set` **dateModified**(`date`): `void`
#### Parameters
• **date**: `Date`
#### Returns
`Date`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`dateModified`](MarkupAnnotation.md#datemodified)
***
### hasChanges
> `get` **hasChanges**(): `boolean`
**`Experimental`**
Indicates if the annotation has been changed since the document was opened
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`hasChanges`](MarkupAnnotation.md#haschanges)
***
### hidden
> `get` **hidden**(): `boolean`
If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user.
> `set` **hidden**(`hidden`): `void`
#### Parameters
• **hidden**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`hidden`](MarkupAnnotation.md#hidden)
***
### id
> `get` **id**(): `void`
**`Experimental`**
A unique identifier for the annotation.
#### Returns
`void`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`id`](MarkupAnnotation.md#id)
***
### interactive
> `get` **interactive**(): `boolean`
Specifies whether the annotation allows user interaction.
> `set` **interactive**(`interactive`): `void`
#### Parameters
• **interactive**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`interactive`](MarkupAnnotation.md#interactive)
***
### isAdded
> `get` **isAdded**(): `boolean`
**`Experimental`**
Indicates whether the annotation was added to a page
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`isAdded`](MarkupAnnotation.md#isadded)
***
### isMaintainingAspectRatio
> `get` **isMaintainingAspectRatio**(): `boolean`
Indicates if the annotation is maintaining its aspect ratio
#### Returns
`boolean`
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`isMaintainingAspectRatio`](MarkupAnnotation.md#ismaintainingaspectratio)
***
### isMarkupAnnotation
> `get` **isMarkupAnnotation**(): `boolean`
Indicates if the annotation is a markup annotation
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`isMarkupAnnotation`](MarkupAnnotation.md#ismarkupannotation)
***
### isModified
> `get` **isModified**(): `boolean`
**`Experimental`**
Indicates if the annotation has changes that have not yet been saved to
the document
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`isModified`](MarkupAnnotation.md#ismodified)
***
### isMoveable
> `get` **isMoveable**(): `boolean`
Indicates if the annotation can be moved by the user
#### Returns
`boolean`
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`isMoveable`](MarkupAnnotation.md#ismoveable)
***
### isResizable
> `get` **isResizable**(): `boolean`
Indicates if the annotation can be resized by the user
#### Returns
`boolean`
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`isResizable`](MarkupAnnotation.md#isresizable)
***
### isRotatable
> `get` **isRotatable**(): `boolean`
Indicates if the annotation can be rotated by the user
#### Returns
`boolean`
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`isRotatable`](MarkupAnnotation.md#isrotatable)
***
### isSelectable
> `get` **isSelectable**(): `boolean`
Indicates if the annotation can be selected by the user
#### Returns
`boolean`
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`isSelectable`](MarkupAnnotation.md#isselectable)
***
### isWidgetAnnotation
> `get` **isWidgetAnnotation**(): `boolean`
Indicates if the annotation is a widget annotation
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`isWidgetAnnotation`](MarkupAnnotation.md#iswidgetannotation)
***
### locked
> `get` **locked**(): [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
Represents the locked state of the annotation.
> `set` **locked**(`locked`): `void`
#### Parameters
• **locked**: [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
#### Returns
[`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`locked`](MarkupAnnotation.md#locked)
***
### modificationDate
> `get` **modificationDate**(): `Date`
The date and time when the annotation was last modified.
This property will retrieve the modification date from the annotation
and convert it to a JavaScript Date object.
#### Returns
`Date`
The modification date as a JavaScript Date object, or `null` if no
modification date is available in the annotation.
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`modificationDate`](MarkupAnnotation.md#modificationdate)
***
### opacity
> `get` **opacity**(): `number`
**`Experimental`**
Annotation opacity
> `set` **opacity**(`opacity`): `void`
#### Parameters
• **opacity**: `number`
#### Returns
`number`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`opacity`](MarkupAnnotation.md#opacity)
***
### page
> `get` **page**(): [`Page`](../../../classes/Page.md)
Page in which the annotation is embedded.
> `set` **page**(`page`): `void`
Set the page in which the annotation is embedded.
#### Parameters
• **page**: [`Page`](../../../classes/Page.md)
The page to set as the annotation's page.
#### Returns
[`Page`](../../../classes/Page.md)
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`page`](MarkupAnnotation.md#page)
***
### pageNumber
> `get` **pageNumber**(): `number`
**`Experimental`**
Number of the page in which the annotation is embedded.
#### Returns
`number`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`pageNumber`](MarkupAnnotation.md#pagenumber)
***
### privateData
> `get` **privateData**(): `object`
**`Experimental`**
Custom data to be stored with the annotation
> `set` **privateData**(`privateData`): `void`
#### Parameters
• **privateData**: `object`
#### Returns
`object`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`privateData`](MarkupAnnotation.md#privatedata)
***
### renderProperties
> `get` **renderProperties**(): [`AnnotationRenderProperties`](AnnotationRenderProperties.md)
Object which encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its visibility, interactivity, and other rendering behaviors.
> `set` **renderProperties**(`v`): `void`
#### Parameters
• **v**: [`AnnotationRenderProperties`](AnnotationRenderProperties.md)
#### Returns
[`AnnotationRenderProperties`](AnnotationRenderProperties.md)
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`renderProperties`](MarkupAnnotation.md#renderproperties)
***
### source
> `get` **source**(): `void`
**`Experimental`**
Tag that identifies the source the annotation is coming from, if
the source is an input PDF or an input FDF.
Newly created annotations always return `null`.
#### Returns
`void`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`source`](MarkupAnnotation.md#source)
***
### subject
> `get` **subject**(): `string`
The subject.
> `set` **subject**(`subject`): `void`
#### Parameters
• **subject**: `string`
#### Returns
`string`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`subject`](MarkupAnnotation.md#subject)
***
### type
> `get` **type**(): [`AnnotationType`](../enumerations/AnnotationType.md)
The PDF annotation type
#### Returns
[`AnnotationType`](../enumerations/AnnotationType.md)
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`type`](MarkupAnnotation.md#type)
## Methods
### dispose()
> **dispose**(): `void`
Disposes of the object, releasing any resources it holds.
The `dispose` method is responsible for performing cleanup operations and releasing
any resources acquired by the object. Once an object is disposed, it should not
be used, and attempts to do so may result in undefined behavior.
#### Returns
`void`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`dispose`](MarkupAnnotation.md#dispose)
***
### rebuild()
> **rebuild**(`data`): `Promise`\<`void`\>
**`Experimental`**
Update stamp data and rebuild the annotation while keeping history and replies.
#### Parameters
• **data**: [`StampData`](../type-aliases/StampData.md)
#### Returns
`Promise`\<`void`\>
---
## Class: TextMarkupAnnotation
**`Experimental`**
Base class for text markup annotations
## Extends
- [`MarkupAnnotation`](MarkupAnnotation.md)
## Constructors
### new TextMarkupAnnotation()
> **new TextMarkupAnnotation**(`options`): [`TextMarkupAnnotation`](TextMarkupAnnotation.md)
**`Experimental`**
#### Parameters
• **options**: [`TextMarkupAnnotationOptions`](../interfaces/TextMarkupAnnotationOptions.md)
Options used to initialize annotation.
#### Returns
[`TextMarkupAnnotation`](TextMarkupAnnotation.md)
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`constructor`](MarkupAnnotation.md#constructors)
## Accessors
### \_\_annotation
> `get` **\_\_annotation**(): `TextMarkupAnnotation`
**`Experimental`**
> `set` **\_\_annotation**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: `TextMarkupAnnotation`
#### Returns
`TextMarkupAnnotation`
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`__annotation`](MarkupAnnotation.md#__annotation)
***
### author
> `get` **author**(): `string`
**`Experimental`**
The author.
> `set` **author**(`author`): `void`
**`Experimental`**
#### Parameters
• **author**: `string`
#### Returns
`string`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`author`](MarkupAnnotation.md#author)
***
### blendMode
> `get` **blendMode**(): [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
**`Experimental`**
blend mode
> `set` **blendMode**(`blendMode`): `void`
**`Experimental`**
#### Parameters
• **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
#### Returns
[`BlendMode`](../../Drawing/enumerations/BlendMode.md)
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`blendMode`](MarkupAnnotation.md#blendmode)
***
### boundingBox
> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
**`Experimental`**
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
> `set` **boundingBox**(`rectangle`): `void`
**`Experimental`**
#### Parameters
• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Returns
[`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`boundingBox`](MarkupAnnotation.md#boundingbox)
***
### content
> `get` **content**(): `string`
**`Experimental`**
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
> `set` **content**(`content`): `void`
**`Experimental`**
#### Parameters
• **content**: `string`
#### Returns
`string`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`content`](MarkupAnnotation.md#content)
***
### creationDate
> `get` **creationDate**(): `Date`
**`Experimental`**
The date and time when the annotation was created.
This property retrieves the creation date from the annotation
and converts it to a JavaScript Date object.
#### Returns
`Date`
The creation date as a JavaScript Date object, or `null` if no
creation date is available in the annotation.
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`creationDate`](MarkupAnnotation.md#creationdate)
***
### dateModified
> `get` **dateModified**(): `Date`
**`Experimental`**
The date and time when the annotation was most recently modified.
> `set` **dateModified**(`date`): `void`
**`Experimental`**
#### Parameters
• **date**: `Date`
#### Returns
`Date`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`dateModified`](MarkupAnnotation.md#datemodified)
***
### fillColor
> `get` **fillColor**(): [`RgbColor`](../../Drawing/classes/RgbColor.md)
**`Experimental`**
Retrieves the fill color used in the annotation.
> `set` **fillColor**(`v`): `void`
**`Experimental`**
Sets the fill color for the annotation.
#### Parameters
• **v**: [`RgbColor`](../../Drawing/classes/RgbColor.md)
The new [RgbColor](../../Drawing/classes/RgbColor.md) to apply to the annotation.
#### Returns
[`RgbColor`](../../Drawing/classes/RgbColor.md)
The [RgbColor](../../Drawing/classes/RgbColor.md) representing the annotation's fill color.
***
### hasChanges
> `get` **hasChanges**(): `boolean`
**`Experimental`**
Indicates if the annotation has been changed since the document was opened
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`hasChanges`](MarkupAnnotation.md#haschanges)
***
### hidden
> `get` **hidden**(): `boolean`
**`Experimental`**
If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user.
> `set` **hidden**(`hidden`): `void`
**`Experimental`**
#### Parameters
• **hidden**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`hidden`](MarkupAnnotation.md#hidden)
***
### id
> `get` **id**(): `void`
**`Experimental`**
A unique identifier for the annotation.
#### Returns
`void`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`id`](MarkupAnnotation.md#id)
***
### interactive
> `get` **interactive**(): `boolean`
**`Experimental`**
Specifies whether the annotation allows user interaction.
> `set` **interactive**(`interactive`): `void`
**`Experimental`**
#### Parameters
• **interactive**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`interactive`](MarkupAnnotation.md#interactive)
***
### isAdded
> `get` **isAdded**(): `boolean`
**`Experimental`**
Indicates whether the annotation was added to a page
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`isAdded`](MarkupAnnotation.md#isadded)
***
### isMaintainingAspectRatio
> `get` **isMaintainingAspectRatio**(): `boolean`
**`Experimental`**
Indicates if the annotation is maintaining its aspect ratio
#### Returns
`boolean`
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`isMaintainingAspectRatio`](MarkupAnnotation.md#ismaintainingaspectratio)
***
### isMarkupAnnotation
> `get` **isMarkupAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a markup annotation
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`isMarkupAnnotation`](MarkupAnnotation.md#ismarkupannotation)
***
### isModified
> `get` **isModified**(): `boolean`
**`Experimental`**
Indicates if the annotation has changes that have not yet been saved to
the document
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`isModified`](MarkupAnnotation.md#ismodified)
***
### isMoveable
> `get` **isMoveable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be moved by the user
#### Returns
`boolean`
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`isMoveable`](MarkupAnnotation.md#ismoveable)
***
### isResizable
> `get` **isResizable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be resized by the user
#### Returns
`boolean`
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`isResizable`](MarkupAnnotation.md#isresizable)
***
### isRotatable
> `get` **isRotatable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be rotated by the user
#### Returns
`boolean`
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`isRotatable`](MarkupAnnotation.md#isrotatable)
***
### isSelectable
> `get` **isSelectable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be selected by the user
#### Returns
`boolean`
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`isSelectable`](MarkupAnnotation.md#isselectable)
***
### isWidgetAnnotation
> `get` **isWidgetAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a widget annotation
#### Returns
`boolean`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`isWidgetAnnotation`](MarkupAnnotation.md#iswidgetannotation)
***
### locked
> `get` **locked**(): [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
**`Experimental`**
Represents the locked state of the annotation.
> `set` **locked**(`locked`): `void`
**`Experimental`**
#### Parameters
• **locked**: [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
#### Returns
[`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`locked`](MarkupAnnotation.md#locked)
***
### modificationDate
> `get` **modificationDate**(): `Date`
**`Experimental`**
The date and time when the annotation was last modified.
This property will retrieve the modification date from the annotation
and convert it to a JavaScript Date object.
#### Returns
`Date`
The modification date as a JavaScript Date object, or `null` if no
modification date is available in the annotation.
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`modificationDate`](MarkupAnnotation.md#modificationdate)
***
### opacity
> `get` **opacity**(): `number`
**`Experimental`**
Annotation opacity
> `set` **opacity**(`opacity`): `void`
**`Experimental`**
#### Parameters
• **opacity**: `number`
#### Returns
`number`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`opacity`](MarkupAnnotation.md#opacity)
***
### page
> `get` **page**(): [`Page`](../../../classes/Page.md)
**`Experimental`**
Page in which the annotation is embedded.
> `set` **page**(`page`): `void`
**`Experimental`**
Set the page in which the annotation is embedded.
#### Parameters
• **page**: [`Page`](../../../classes/Page.md)
The page to set as the annotation's page.
#### Returns
[`Page`](../../../classes/Page.md)
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`page`](MarkupAnnotation.md#page)
***
### pageNumber
> `get` **pageNumber**(): `number`
**`Experimental`**
Number of the page in which the annotation is embedded.
#### Returns
`number`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`pageNumber`](MarkupAnnotation.md#pagenumber)
***
### privateData
> `get` **privateData**(): `object`
**`Experimental`**
Custom data to be stored with the annotation
> `set` **privateData**(`privateData`): `void`
**`Experimental`**
#### Parameters
• **privateData**: `object`
#### Returns
`object`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`privateData`](MarkupAnnotation.md#privatedata)
***
### renderProperties
> `get` **renderProperties**(): [`AnnotationRenderProperties`](AnnotationRenderProperties.md)
**`Experimental`**
Object which encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its visibility, interactivity, and other rendering behaviors.
> `set` **renderProperties**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: [`AnnotationRenderProperties`](AnnotationRenderProperties.md)
#### Returns
[`AnnotationRenderProperties`](AnnotationRenderProperties.md)
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`renderProperties`](MarkupAnnotation.md#renderproperties)
***
### source
> `get` **source**(): `void`
**`Experimental`**
Tag that identifies the source the annotation is coming from, if
the source is an input PDF or an input FDF.
Newly created annotations always return `null`.
#### Returns
`void`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`source`](MarkupAnnotation.md#source)
***
### subject
> `get` **subject**(): `string`
**`Experimental`**
The subject.
> `set` **subject**(`subject`): `void`
**`Experimental`**
#### Parameters
• **subject**: `string`
#### Returns
`string`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`subject`](MarkupAnnotation.md#subject)
***
### subtype
> `get` **subtype**(): `TextMarkupType`
**`Experimental`**
Retrieves the type of markup applied by this annotation.
#### Returns
`TextMarkupType`
The TextMarkupType representing how the text is marked,
such as highlight, underline, strikethrough, or squiggly.
***
### textMarkupArea
> `get` **textMarkupArea**(): [`Quadrilateral`](../../Geometry/classes/Quadrilateral.md)\<`PdfPoint`\>[]
**`Experimental`**
Retrieves the area marked by this annotation.
This represents the set of quadrilateral regions that highlight or mark
portions of text within the document.
#### Returns
[`Quadrilateral`](../../Geometry/classes/Quadrilateral.md)\<`PdfPoint`\>[]
An array of [Quadrilateral](../../Geometry/classes/Quadrilateral.md) defining the marked-up area.
***
### type
> `get` **type**(): [`AnnotationType`](../enumerations/AnnotationType.md)
**`Experimental`**
The PDF annotation type
#### Returns
[`AnnotationType`](../enumerations/AnnotationType.md)
#### Overrides
[`MarkupAnnotation`](MarkupAnnotation.md).[`type`](MarkupAnnotation.md#type)
***
### underlyingText
> `get` **underlyingText**(): `string`
**`Experimental`**
Retrieves the text associated with the text markup annotation as a string.
#### Remarks
This method provides a convenient way to access the text marked by the annotation,
but it does not directly originate from the annotation object within the PDF structure.
Due to potential complexities such as overlapping texts or watermarks,
the returned string might not always precisely match the visually selected content.
#### Returns
`string`
The text associated with the annotation.
## Methods
### dispose()
> **dispose**(): `void`
**`Experimental`**
#### Returns
`void`
#### Inherited from
[`MarkupAnnotation`](MarkupAnnotation.md).[`dispose`](MarkupAnnotation.md#dispose)
---
## Class: WatermarkAnnotation
**`Experimental`**
A watermark annotation
## Extends
- [`Annotation`](Annotation.md)
## Constructors
### new WatermarkAnnotation()
> **new WatermarkAnnotation**(`options`): [`WatermarkAnnotation`](WatermarkAnnotation.md)
**`Experimental`**
#### Parameters
• **options**: [`WatermarkAnnotationOptions`](../interfaces/WatermarkAnnotationOptions.md)
Options used to initialize annotation.
#### Returns
[`WatermarkAnnotation`](WatermarkAnnotation.md)
#### Overrides
[`Annotation`](Annotation.md).[`constructor`](Annotation.md#constructors)
## Properties
### action
> **action**: [`Action`](../../Actions/classes/Action.md)
**`Experimental`**
The action that is performed when the watermark annotation is clicked on
## Accessors
### \_\_annotation
> `get` **\_\_annotation**(): `Annotation`
**`Experimental`**
> `set` **\_\_annotation**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: `Annotation`
#### Returns
`Annotation`
#### Inherited from
[`Annotation`](Annotation.md).[`__annotation`](Annotation.md#__annotation)
***
### boundingBox
> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
**`Experimental`**
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
> `set` **boundingBox**(`rectangle`): `void`
**`Experimental`**
#### Parameters
• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Returns
[`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Inherited from
[`Annotation`](Annotation.md).[`boundingBox`](Annotation.md#boundingbox)
***
### content
> `get` **content**(): `string`
**`Experimental`**
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
> `set` **content**(`content`): `void`
**`Experimental`**
#### Parameters
• **content**: `string`
#### Returns
`string`
#### Inherited from
[`Annotation`](Annotation.md).[`content`](Annotation.md#content)
***
### dateModified
> `get` **dateModified**(): `Date`
**`Experimental`**
The date and time when the annotation was most recently modified.
> `set` **dateModified**(`date`): `void`
**`Experimental`**
#### Parameters
• **date**: `Date`
#### Returns
`Date`
#### Inherited from
[`Annotation`](Annotation.md).[`dateModified`](Annotation.md#datemodified)
***
### hasChanges
> `get` **hasChanges**(): `boolean`
**`Experimental`**
Indicates if the annotation has been changed since the document was opened
#### Returns
`boolean`
#### Inherited from
[`Annotation`](Annotation.md).[`hasChanges`](Annotation.md#haschanges)
***
### hidden
> `get` **hidden**(): `boolean`
**`Experimental`**
If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user.
> `set` **hidden**(`hidden`): `void`
**`Experimental`**
#### Parameters
• **hidden**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`Annotation`](Annotation.md).[`hidden`](Annotation.md#hidden)
***
### id
> `get` **id**(): `void`
**`Experimental`**
A unique identifier for the annotation.
#### Returns
`void`
#### Inherited from
[`Annotation`](Annotation.md).[`id`](Annotation.md#id)
***
### interactive
> `get` **interactive**(): `boolean`
**`Experimental`**
Specifies whether the annotation allows user interaction.
> `set` **interactive**(`interactive`): `void`
**`Experimental`**
#### Parameters
• **interactive**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`Annotation`](Annotation.md).[`interactive`](Annotation.md#interactive)
***
### isAdded
> `get` **isAdded**(): `boolean`
**`Experimental`**
Indicates whether the annotation was added to a page
#### Returns
`boolean`
#### Inherited from
[`Annotation`](Annotation.md).[`isAdded`](Annotation.md#isadded)
***
### isMaintainingAspectRatio
> `get` **isMaintainingAspectRatio**(): `boolean`
**`Experimental`**
Indicates if the annotation is maintaining its aspect ratio
#### Returns
`boolean`
#### Overrides
[`Annotation`](Annotation.md).[`isMaintainingAspectRatio`](Annotation.md#ismaintainingaspectratio)
***
### isMarkupAnnotation
> `get` **isMarkupAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a markup annotation
#### Returns
`boolean`
#### Overrides
[`Annotation`](Annotation.md).[`isMarkupAnnotation`](Annotation.md#ismarkupannotation)
***
### isModified
> `get` **isModified**(): `boolean`
**`Experimental`**
Indicates if the annotation has changes that have not yet been saved to
the document
#### Returns
`boolean`
#### Inherited from
[`Annotation`](Annotation.md).[`isModified`](Annotation.md#ismodified)
***
### isMoveable
> `get` **isMoveable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be moved by the user
#### Returns
`boolean`
#### Overrides
[`Annotation`](Annotation.md).[`isMoveable`](Annotation.md#ismoveable)
***
### isResizable
> `get` **isResizable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be resized by the user
#### Returns
`boolean`
#### Overrides
[`Annotation`](Annotation.md).[`isResizable`](Annotation.md#isresizable)
***
### isRotatable
> `get` **isRotatable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be rotated by the user
#### Returns
`boolean`
#### Overrides
[`Annotation`](Annotation.md).[`isRotatable`](Annotation.md#isrotatable)
***
### isSelectable
> `get` **isSelectable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be selected by the user
#### Returns
`boolean`
#### Overrides
[`Annotation`](Annotation.md).[`isSelectable`](Annotation.md#isselectable)
***
### isWidgetAnnotation
> `get` **isWidgetAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a widget annotation
#### Returns
`boolean`
#### Overrides
[`Annotation`](Annotation.md).[`isWidgetAnnotation`](Annotation.md#iswidgetannotation)
***
### locked
> `get` **locked**(): [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
**`Experimental`**
Represents the locked state of the annotation.
> `set` **locked**(`locked`): `void`
**`Experimental`**
#### Parameters
• **locked**: [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
#### Returns
[`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
#### Inherited from
[`Annotation`](Annotation.md).[`locked`](Annotation.md#locked)
***
### page
> `get` **page**(): [`Page`](../../../classes/Page.md)
**`Experimental`**
Page in which the annotation is embedded.
> `set` **page**(`page`): `void`
**`Experimental`**
Set the page in which the annotation is embedded.
#### Parameters
• **page**: [`Page`](../../../classes/Page.md)
The page to set as the annotation's page.
#### Returns
[`Page`](../../../classes/Page.md)
#### Inherited from
[`Annotation`](Annotation.md).[`page`](Annotation.md#page)
***
### pageNumber
> `get` **pageNumber**(): `number`
**`Experimental`**
Number of the page in which the annotation is embedded.
#### Returns
`number`
#### Inherited from
[`Annotation`](Annotation.md).[`pageNumber`](Annotation.md#pagenumber)
***
### privateData
> `get` **privateData**(): `object`
**`Experimental`**
Custom data to be stored with the annotation
> `set` **privateData**(`privateData`): `void`
**`Experimental`**
#### Parameters
• **privateData**: `object`
#### Returns
`object`
#### Inherited from
[`Annotation`](Annotation.md).[`privateData`](Annotation.md#privatedata)
***
### renderProperties
> `get` **renderProperties**(): [`AnnotationRenderProperties`](AnnotationRenderProperties.md)
**`Experimental`**
Object which encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its visibility, interactivity, and other rendering behaviors.
> `set` **renderProperties**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: [`AnnotationRenderProperties`](AnnotationRenderProperties.md)
#### Returns
[`AnnotationRenderProperties`](AnnotationRenderProperties.md)
#### Inherited from
[`Annotation`](Annotation.md).[`renderProperties`](Annotation.md#renderproperties)
***
### source
> `get` **source**(): `void`
**`Experimental`**
Tag that identifies the source the annotation is coming from, if
the source is an input PDF or an input FDF.
Newly created annotations always return `null`.
#### Returns
`void`
#### Inherited from
[`Annotation`](Annotation.md).[`source`](Annotation.md#source)
***
### type
> `get` **type**(): [`AnnotationType`](../enumerations/AnnotationType.md)
**`Experimental`**
The PDF annotation type
#### Default Value
`AnnotationType.Watermark`
#### Returns
[`AnnotationType`](../enumerations/AnnotationType.md)
#### Overrides
[`Annotation`](Annotation.md).[`type`](Annotation.md#type)
## Methods
### dispose()
> **dispose**(): `void`
**`Experimental`**
#### Returns
`void`
#### Inherited from
[`Annotation`](Annotation.md).[`dispose`](Annotation.md#dispose)
---
## Class: WidgetAnnotation
**`Experimental`**
A widget annotation
## Extends
- [`Annotation`](Annotation.md)
## Extended by
- [`ButtonWidget`](../../Forms/classes/ButtonWidget.md)
- [`CheckBoxWidget`](../../Forms/classes/CheckBoxWidget.md)
- [`ComboBoxWidget`](../../Forms/classes/ComboBoxWidget.md)
- [`FormWidget`](../../Forms/classes/FormWidget.md)
- [`ListBoxWidget`](../../Forms/classes/ListBoxWidget.md)
- [`RadioButtonWidget`](../../Forms/classes/RadioButtonWidget.md)
- [`TextBoxWidget`](../../Forms/classes/TextBoxWidget.md)
## Constructors
### new WidgetAnnotation()
> **new WidgetAnnotation**(`options`): [`WidgetAnnotation`](WidgetAnnotation.md)
**`Experimental`**
#### Parameters
• **options**: [`WidgetAnnotationOptions`](../interfaces/WidgetAnnotationOptions.md)
Options used to initialize annotation.
#### Returns
[`WidgetAnnotation`](WidgetAnnotation.md)
#### Overrides
[`Annotation`](Annotation.md).[`constructor`](Annotation.md#constructors)
## Properties
### action
> **action**: [`Action`](../../Actions/classes/Action.md)
**`Experimental`**
The action that is performed when the widget annotation is clicked on
## Accessors
### \_\_annotation
> `get` **\_\_annotation**(): `Annotation`
**`Experimental`**
> `set` **\_\_annotation**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: `Annotation`
#### Returns
`Annotation`
#### Inherited from
[`Annotation`](Annotation.md).[`__annotation`](Annotation.md#__annotation)
***
### boundingBox
> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
**`Experimental`**
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
> `set` **boundingBox**(`rectangle`): `void`
**`Experimental`**
#### Parameters
• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Returns
[`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Inherited from
[`Annotation`](Annotation.md).[`boundingBox`](Annotation.md#boundingbox)
***
### content
> `get` **content**(): `string`
**`Experimental`**
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
> `set` **content**(`content`): `void`
**`Experimental`**
#### Parameters
• **content**: `string`
#### Returns
`string`
#### Inherited from
[`Annotation`](Annotation.md).[`content`](Annotation.md#content)
***
### dateModified
> `get` **dateModified**(): `Date`
**`Experimental`**
The date and time when the annotation was most recently modified.
> `set` **dateModified**(`date`): `void`
**`Experimental`**
#### Parameters
• **date**: `Date`
#### Returns
`Date`
#### Inherited from
[`Annotation`](Annotation.md).[`dateModified`](Annotation.md#datemodified)
***
### hasChanges
> `get` **hasChanges**(): `boolean`
**`Experimental`**
Indicates if the annotation has been changed since the document was opened
#### Returns
`boolean`
#### Inherited from
[`Annotation`](Annotation.md).[`hasChanges`](Annotation.md#haschanges)
***
### hidden
> `get` **hidden**(): `boolean`
**`Experimental`**
If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user.
> `set` **hidden**(`hidden`): `void`
**`Experimental`**
#### Parameters
• **hidden**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`Annotation`](Annotation.md).[`hidden`](Annotation.md#hidden)
***
### id
> `get` **id**(): `void`
**`Experimental`**
A unique identifier for the annotation.
#### Returns
`void`
#### Inherited from
[`Annotation`](Annotation.md).[`id`](Annotation.md#id)
***
### interactive
> `get` **interactive**(): `boolean`
**`Experimental`**
Specifies whether the annotation allows user interaction.
> `set` **interactive**(`interactive`): `void`
**`Experimental`**
#### Parameters
• **interactive**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`Annotation`](Annotation.md).[`interactive`](Annotation.md#interactive)
***
### isAdded
> `get` **isAdded**(): `boolean`
**`Experimental`**
Indicates whether the annotation was added to a page
#### Returns
`boolean`
#### Inherited from
[`Annotation`](Annotation.md).[`isAdded`](Annotation.md#isadded)
***
### isMaintainingAspectRatio
> `get` **isMaintainingAspectRatio**(): `boolean`
**`Experimental`**
Indicates if the annotation is maintaining its aspect ratio
#### Returns
`boolean`
#### Overrides
[`Annotation`](Annotation.md).[`isMaintainingAspectRatio`](Annotation.md#ismaintainingaspectratio)
***
### isMarkupAnnotation
> `get` **isMarkupAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a markup annotation
#### Returns
`boolean`
#### Overrides
[`Annotation`](Annotation.md).[`isMarkupAnnotation`](Annotation.md#ismarkupannotation)
***
### isModified
> `get` **isModified**(): `boolean`
**`Experimental`**
Indicates if the annotation has changes that have not yet been saved to
the document
#### Returns
`boolean`
#### Inherited from
[`Annotation`](Annotation.md).[`isModified`](Annotation.md#ismodified)
***
### isMoveable
> `get` **isMoveable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be moved by the user
#### Returns
`boolean`
#### Overrides
[`Annotation`](Annotation.md).[`isMoveable`](Annotation.md#ismoveable)
***
### isResizable
> `get` **isResizable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be resized by the user
#### Returns
`boolean`
#### Overrides
[`Annotation`](Annotation.md).[`isResizable`](Annotation.md#isresizable)
***
### isRotatable
> `get` **isRotatable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be rotated by the user
#### Returns
`boolean`
#### Overrides
[`Annotation`](Annotation.md).[`isRotatable`](Annotation.md#isrotatable)
***
### isSelectable
> `get` **isSelectable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be selected by the user
#### Returns
`boolean`
#### Overrides
[`Annotation`](Annotation.md).[`isSelectable`](Annotation.md#isselectable)
***
### isWidgetAnnotation
> `get` **isWidgetAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a widget annotation
#### Returns
`boolean`
#### Overrides
[`Annotation`](Annotation.md).[`isWidgetAnnotation`](Annotation.md#iswidgetannotation)
***
### locked
> `get` **locked**(): [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
**`Experimental`**
Represents the locked state of the annotation.
> `set` **locked**(`locked`): `void`
**`Experimental`**
#### Parameters
• **locked**: [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
#### Returns
[`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)
#### Inherited from
[`Annotation`](Annotation.md).[`locked`](Annotation.md#locked)
***
### page
> `get` **page**(): [`Page`](../../../classes/Page.md)
**`Experimental`**
Page in which the annotation is embedded.
> `set` **page**(`page`): `void`
**`Experimental`**
Set the page in which the annotation is embedded.
#### Parameters
• **page**: [`Page`](../../../classes/Page.md)
The page to set as the annotation's page.
#### Returns
[`Page`](../../../classes/Page.md)
#### Inherited from
[`Annotation`](Annotation.md).[`page`](Annotation.md#page)
***
### pageNumber
> `get` **pageNumber**(): `number`
**`Experimental`**
Number of the page in which the annotation is embedded.
#### Returns
`number`
#### Inherited from
[`Annotation`](Annotation.md).[`pageNumber`](Annotation.md#pagenumber)
***
### privateData
> `get` **privateData**(): `object`
**`Experimental`**
Custom data to be stored with the annotation
> `set` **privateData**(`privateData`): `void`
**`Experimental`**
#### Parameters
• **privateData**: `object`
#### Returns
`object`
#### Inherited from
[`Annotation`](Annotation.md).[`privateData`](Annotation.md#privatedata)
***
### renderProperties
> `get` **renderProperties**(): [`AnnotationRenderProperties`](AnnotationRenderProperties.md)
**`Experimental`**
Object which encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its visibility, interactivity, and other rendering behaviors.
> `set` **renderProperties**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: [`AnnotationRenderProperties`](AnnotationRenderProperties.md)
#### Returns
[`AnnotationRenderProperties`](AnnotationRenderProperties.md)
#### Inherited from
[`Annotation`](Annotation.md).[`renderProperties`](Annotation.md#renderproperties)
***
### source
> `get` **source**(): `void`
**`Experimental`**
Tag that identifies the source the annotation is coming from, if
the source is an input PDF or an input FDF.
Newly created annotations always return `null`.
#### Returns
`void`
#### Inherited from
[`Annotation`](Annotation.md).[`source`](Annotation.md#source)
***
### type
> `get` **type**(): [`AnnotationType`](../enumerations/AnnotationType.md)
**`Experimental`**
The PDF annotation type
#### Default Value
`AnnotationType.Widget`
#### Returns
[`AnnotationType`](../enumerations/AnnotationType.md)
#### Overrides
[`Annotation`](Annotation.md).[`type`](Annotation.md#type)
## Methods
### dispose()
> **dispose**(): `void`
**`Experimental`**
#### Returns
`void`
#### Inherited from
[`Annotation`](Annotation.md).[`dispose`](Annotation.md#dispose)
---
## Enumeration: AnnotationLockedState
## Enumeration Members
### All
> **All**: `3`
Fully locked, preventing deletion, modification of position and size, and changes to contents.
***
### Container
> **Container**: `1`
Locked to prevent modification or deletion of the annotation's position and size, excluding its contents.
***
### Content
> **Content**: `2`
Locked to prevent modifications to the annotation's contents, but allows changes to position and size.
***
### None
> **None**: `0`
No locking restrictions.
---
## Enumeration: AnnotationType
Annotation Type
## Enumeration Members
### 3D
> **3D**: `24`
***
### Caret
> **Caret**: `12`
***
### Circle
> **Circle**: `8`
***
### FileAttachment
> **FileAttachment**: `15`
***
### FreeText
> **FreeText**: `5`
***
### Ink
> **Ink**: `13`
***
### InternalLink
> **InternalLink**: `3`
***
### Line
> **Line**: `6`
***
### Link
> **Link**: `1`
***
### Movie
> **Movie**: `17`
***
### PolyLine
> **PolyLine**: `10`
***
### Polygon
> **Polygon**: `9`
***
### Popup
> **Popup**: `14`
***
### PrinterMark
> **PrinterMark**: `20`
***
### Redact
> **Redact**: `23`
***
### Screen
> **Screen**: `19`
***
### Sound
> **Sound**: `16`
***
### Square
> **Square**: `7`
***
### Stamp
> **Stamp**: `11`
***
### Text
> **Text**: `0`
***
### TextMarkup
> **TextMarkup**: `4`
***
### TrapNet
> **TrapNet**: `21`
***
### Watermark
> **Watermark**: `22`
***
### WebLink
> **WebLink**: `2`
***
### Widget
> **Widget**: `18`
---
## Enumeration: FileAttachmentAnnotationIcon
Specifies the type of icon displayed on a page for a .
## Enumeration Members
### CustomIcon
> **CustomIcon**: `127`
***
### Graph
> **Graph**: `0`
***
### Paperclip
> **Paperclip**: `2`
***
### PushPin
> **PushPin**: `1`
***
### Tag
> **Tag**: `3`
---
## Enumeration: NoteAnnotationIcon
Icons for note annotation
## Enumeration Members
### Check
> **Check**: `8`
***
### CheckMark
> **CheckMark**: `9`
***
### Circle
> **Circle**: `7`
***
### Comment
> **Comment**: `0`
***
### Cross
> **Cross**: `10`
***
### CrossHairs
> **CrossHairs**: `11`
***
### Help
> **Help**: `3`
***
### Insert
> **Insert**: `6`
***
### Key
> **Key**: `1`
***
### NewParagraph
> **NewParagraph**: `4`
***
### Note
> **Note**: `2`
***
### Paragraph
> **Paragraph**: `5`
***
### RightArrow
> **RightArrow**: `12`
***
### RightPointer
> **RightPointer**: `13`
***
### Star
> **Star**: `14`
***
### UpArrow
> **UpArrow**: `15`
***
### UpLeftArrow
> **UpLeftArrow**: `16`
---
## Enumeration: PredefinedTextStampType(Enumerations)
An enum defining predefined text stamp types.
## Enumeration Members
### Approved
> **Approved**: `0`
***
### AsIs
> **AsIs**: `3`
***
### Completed
> **Completed**: `14`
***
### Confidential
> **Confidential**: `6`
***
### CustomStampText
> **CustomStampText**: `18`
***
### Departmental
> **Departmental**: `9`
***
### Draft
> **Draft**: `12`
***
### Experimental
> **Experimental**: `1`
***
### Expired
> **Expired**: `4`
***
### Final
> **Final**: `7`
***
### ForComment
> **ForComment**: `10`
***
### ForPublicRelease
> **ForPublicRelease**: `13`
***
### InformationOnly
> **InformationOnly**: `17`
***
### NotApproved
> **NotApproved**: `2`
***
### NotForPublicRelease
> **NotForPublicRelease**: `5`
***
### PreliminaryResults
> **PreliminaryResults**: `16`
***
### Sold
> **Sold**: `8`
***
### TopSecret
> **TopSecret**: `11`
***
### Void
> **Void**: `15`
---
## Enumeration: StampAnnotationSubtype
An enum defining stamp annotation subtypes.
## Enumeration Members
### Custom
> **Custom**: `4`
***
### CustomText
> **CustomText**: `1`
***
### Image
> **Image**: `2`
***
### Pdf
> **Pdf**: `3`
***
### PredefinedText
> **PredefinedText**: `0`
***
### Undefined
> **Undefined**: `5`
---
## Enumeration: StampColor
An enum defining stamp colors.
## Enumeration Members
### Blue
> **Blue**: `2`
***
### Green
> **Green**: `1`
***
### Red
> **Red**: `0`
---
## Annotations
## Index
### Enumerations
- [AnnotationLockedState](enumerations/AnnotationLockedState.md)
- [AnnotationType](enumerations/AnnotationType.md)
- [FileAttachmentAnnotationIcon](enumerations/FileAttachmentAnnotationIcon.md)
- [NoteAnnotationIcon](enumerations/NoteAnnotationIcon.md)
- [PredefinedTextStampType](enumerations/PredefinedTextStampType.md)
- [StampAnnotationSubtype](enumerations/StampAnnotationSubtype.md)
- [StampColor](enumerations/StampColor.md)
### Classes
- [Annotation](classes/Annotation.md)
- [AnnotationRenderProperties](classes/AnnotationRenderProperties.md)
- [CaretAnnotation](classes/CaretAnnotation.md)
- [DrawingAnnotation](classes/DrawingAnnotation.md)
- [EllipseAnnotation](classes/EllipseAnnotation.md)
- [FileAttachmentAnnotation](classes/FileAttachmentAnnotation.md)
- [FreeTextAnnotation](classes/FreeTextAnnotation.md)
- [InkAnnotation](classes/InkAnnotation.md)
- [InternalLinkAnnotation](classes/InternalLinkAnnotation.md)
- [LineAnnotation](classes/LineAnnotation.md)
- [LinkAnnotation](classes/LinkAnnotation.md)
- [MarkupAnnotation](classes/MarkupAnnotation.md)
- [NoteAnnotation](classes/NoteAnnotation.md)
- [PolyLineAnnotation](classes/PolyLineAnnotation.md)
- [PolygonAnnotation](classes/PolygonAnnotation.md)
- [RectangleAnnotation](classes/RectangleAnnotation.md)
- [ShapeAnnotation](classes/ShapeAnnotation.md)
- [StampAnnotation](classes/StampAnnotation.md)
- [TextMarkupAnnotation](classes/TextMarkupAnnotation.md)
- [WatermarkAnnotation](classes/WatermarkAnnotation.md)
- [WidgetAnnotation](classes/WidgetAnnotation.md)
### Interfaces
- [AnnotationOptions](interfaces/AnnotationOptions.md)
- [CaretAnnotationOptions](interfaces/CaretAnnotationOptions.md)
- [CustomStampAnnotationOptions](interfaces/CustomStampAnnotationOptions.md)
- [CustomTextStampAnnotationOptions](interfaces/CustomTextStampAnnotationOptions.md)
- [DrawingAnnotationOptions](interfaces/DrawingAnnotationOptions.md)
- [EllipseAnnotationOptions](interfaces/EllipseAnnotationOptions.md)
- [FileAttachmentAnnotationOptions](interfaces/FileAttachmentAnnotationOptions.md)
- [FreeTextAnnotationOptions](interfaces/FreeTextAnnotationOptions.md)
- [ImageStampAnnotationOptions](interfaces/ImageStampAnnotationOptions.md)
- [InkAnnotationOptions](interfaces/InkAnnotationOptions.md)
- [InternalLinkAnnotationOptions](interfaces/InternalLinkAnnotationOptions.md)
- [LineAnnotationOptions](interfaces/LineAnnotationOptions.md)
- [LinkAnnotationOptions](interfaces/LinkAnnotationOptions.md)
- [MarkupAnnotationOptions](interfaces/MarkupAnnotationOptions.md)
- [NoteAnnotationOptions](interfaces/NoteAnnotationOptions.md)
- [PdfStampAnnotationOptions](interfaces/PdfStampAnnotationOptions.md)
- [PolyLineAnnotationOptions](interfaces/PolyLineAnnotationOptions.md)
- [PolygonAnnotationOptions](interfaces/PolygonAnnotationOptions.md)
- [PredefinedTextStampAnnotationOptions](interfaces/PredefinedTextStampAnnotationOptions.md)
- [RectangleAnnotationOptions](interfaces/RectangleAnnotationOptions.md)
- [ShapeAnnotationOptions](interfaces/ShapeAnnotationOptions.md)
- [StampAnnotationOptions](interfaces/StampAnnotationOptions.md)
- [TextMarkupAnnotationOptions](interfaces/TextMarkupAnnotationOptions.md)
- [WatermarkAnnotationOptions](interfaces/WatermarkAnnotationOptions.md)
- [WidgetAnnotationOptions](interfaces/WidgetAnnotationOptions.md)
### Type Aliases
- [StampData](type-aliases/StampData.md)
---
## Interface: AnnotationOptions
Base options for all annotations
## Extended by
- [`LinkAnnotationOptions`](LinkAnnotationOptions.md)
- [`MarkupAnnotationOptions`](MarkupAnnotationOptions.md)
- [`NoteAnnotationOptions`](NoteAnnotationOptions.md)
- [`WatermarkAnnotationOptions`](WatermarkAnnotationOptions.md)
- [`WidgetAnnotationOptions`](WidgetAnnotationOptions.md)
- [`InternalLinkAnnotationOptions`](InternalLinkAnnotationOptions.md)
## Properties
### boundingBox?
> `optional` **boundingBox**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
#### Default Value
`null`
***
### content?
> `optional` **content**: `string`
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
#### Default Value
`""`
***
### dateModified?
> `optional` **dateModified**: `Date`
The date and time when the annotation was most recently modified.
***
### page
> **page**: [`Page`](../../../classes/Page.md)
Page in which the annotation is embedded.
***
### privateData?
> `optional` **privateData**: `object`
Custom data to be stored with the annotation
#### Default Value
`undefined`
***
### renderProperties?
> `optional` **renderProperties**: [`AnnotationRenderProperties`](../classes/AnnotationRenderProperties.md)
The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its rendering behaviors.
---
## Interface: CaretAnnotationOptions
Base options for all annotations
## Extends
- [`MarkupAnnotationOptions`](MarkupAnnotationOptions.md)
## Properties
### author?
> `optional` **author**: `string`
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`author`](MarkupAnnotationOptions.md#author)
***
### blendMode?
> `optional` **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
**`Experimental`**
blend mode
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`blendMode`](MarkupAnnotationOptions.md#blendmode)
***
### boundingBox?
> `optional` **boundingBox**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
#### Default Value
`null`
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`boundingBox`](MarkupAnnotationOptions.md#boundingbox)
***
### content?
> `optional` **content**: `string`
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
#### Default Value
`""`
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`content`](MarkupAnnotationOptions.md#content)
***
### dateModified?
> `optional` **dateModified**: `Date`
The date and time when the annotation was most recently modified.
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`dateModified`](MarkupAnnotationOptions.md#datemodified)
***
### opacity?
> `optional` **opacity**: `number`
**`Experimental`**
annotation opacity
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`opacity`](MarkupAnnotationOptions.md#opacity)
***
### page
> **page**: [`Page`](../../../classes/Page.md)
Page in which the annotation is embedded.
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`page`](MarkupAnnotationOptions.md#page)
***
### privateData?
> `optional` **privateData**: `object`
Custom data to be stored with the annotation
#### Default Value
`undefined`
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`privateData`](MarkupAnnotationOptions.md#privatedata)
***
### renderProperties?
> `optional` **renderProperties**: [`AnnotationRenderProperties`](../classes/AnnotationRenderProperties.md)
The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its rendering behaviors.
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`renderProperties`](MarkupAnnotationOptions.md#renderproperties)
***
### subject?
> `optional` **subject**: `string`
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`subject`](MarkupAnnotationOptions.md#subject)
---
## Interface: CustomStampAnnotationOptions
**`Experimental`**
An interface specific to Custom stamp annotations, defining custom content used for creating the annotation.
## Properties
### content
> **content**: [`PdfContent`](../../Drawing/interfaces/PdfContent.md)
**`Experimental`**
***
### subtype
> **subtype**: [`Custom`](../enumerations/StampAnnotationSubtype.md#custom)
**`Experimental`**
---
## Interface: CustomTextStampAnnotationOptions
An interface specific to custom text stamp annotations, defining the text and color.
## Properties
### color
> **color**: [`StampColor`](../enumerations/StampColor.md)
***
### subtype
> **subtype**: [`CustomText`](../enumerations/StampAnnotationSubtype.md#customtext)
***
### text
> **text**: `string`
---
## Interface: DrawingAnnotationOptions
Base options for all annotations
## Extends
- [`MarkupAnnotationOptions`](MarkupAnnotationOptions.md)
## Extended by
- [`InkAnnotationOptions`](InkAnnotationOptions.md)
- [`LineAnnotationOptions`](LineAnnotationOptions.md)
- [`PolyLineAnnotationOptions`](PolyLineAnnotationOptions.md)
- [`ShapeAnnotationOptions`](ShapeAnnotationOptions.md)
## Properties
### author?
> `optional` **author**: `string`
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`author`](MarkupAnnotationOptions.md#author)
***
### blendMode?
> `optional` **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
**`Experimental`**
blend mode
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`blendMode`](MarkupAnnotationOptions.md#blendmode)
***
### boundingBox?
> `optional` **boundingBox**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
#### Default Value
`null`
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`boundingBox`](MarkupAnnotationOptions.md#boundingbox)
***
### content?
> `optional` **content**: `string`
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
#### Default Value
`""`
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`content`](MarkupAnnotationOptions.md#content)
***
### dateModified?
> `optional` **dateModified**: `Date`
The date and time when the annotation was most recently modified.
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`dateModified`](MarkupAnnotationOptions.md#datemodified)
***
### opacity?
> `optional` **opacity**: `number`
**`Experimental`**
annotation opacity
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`opacity`](MarkupAnnotationOptions.md#opacity)
***
### page
> **page**: [`Page`](../../../classes/Page.md)
Page in which the annotation is embedded.
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`page`](MarkupAnnotationOptions.md#page)
***
### privateData?
> `optional` **privateData**: `object`
Custom data to be stored with the annotation
#### Default Value
`undefined`
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`privateData`](MarkupAnnotationOptions.md#privatedata)
***
### renderProperties?
> `optional` **renderProperties**: [`AnnotationRenderProperties`](../classes/AnnotationRenderProperties.md)
The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its rendering behaviors.
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`renderProperties`](MarkupAnnotationOptions.md#renderproperties)
***
### stroke?
> `optional` **stroke**: [`Stroke`](../../Drawing/classes/Stroke.md)
annotation stroke
***
### subject?
> `optional` **subject**: `string`
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`subject`](MarkupAnnotationOptions.md#subject)
---
## Interface: EllipseAnnotationOptions
## Extends
- [`ShapeAnnotationOptions`](ShapeAnnotationOptions.md)
## Properties
### author?
> `optional` **author**: `string`
#### Inherited from
[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`author`](ShapeAnnotationOptions.md#author)
***
### blendMode?
> `optional` **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
**`Experimental`**
blend mode
#### Inherited from
[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`blendMode`](ShapeAnnotationOptions.md#blendmode)
***
### borderEffect?
> `optional` **borderEffect**: `BorderEffect`
***
### borderIntensity?
> `optional` **borderIntensity**: `number`
***
### boundingBox?
> `optional` **boundingBox**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
#### Default Value
`null`
#### Inherited from
[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`boundingBox`](ShapeAnnotationOptions.md#boundingbox)
***
### content?
> `optional` **content**: `string`
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
#### Default Value
`""`
#### Inherited from
[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`content`](ShapeAnnotationOptions.md#content)
***
### dateModified?
> `optional` **dateModified**: `Date`
The date and time when the annotation was most recently modified.
#### Inherited from
[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`dateModified`](ShapeAnnotationOptions.md#datemodified)
***
### fill?
> `optional` **fill**: `string`
annotation fill
#### Inherited from
[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`fill`](ShapeAnnotationOptions.md#fill)
***
### fillColor?
> `optional` **fillColor**: [`RgbaColor`](../../Drawing/classes/RgbaColor.md)
***
### lineColor?
> `optional` **lineColor**: [`RgbaColor`](../../Drawing/classes/RgbaColor.md)
***
### lineWidth?
> `optional` **lineWidth**: `number`
***
### opacity?
> `optional` **opacity**: `number`
**`Experimental`**
annotation opacity
#### Inherited from
[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`opacity`](ShapeAnnotationOptions.md#opacity)
***
### page
> **page**: [`Page`](../../../classes/Page.md)
Page in which the annotation is embedded.
#### Inherited from
[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`page`](ShapeAnnotationOptions.md#page)
***
### privateData?
> `optional` **privateData**: `object`
Custom data to be stored with the annotation
#### Default Value
`undefined`
#### Inherited from
[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`privateData`](ShapeAnnotationOptions.md#privatedata)
***
### renderProperties?
> `optional` **renderProperties**: [`AnnotationRenderProperties`](../classes/AnnotationRenderProperties.md)
The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its rendering behaviors.
#### Inherited from
[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`renderProperties`](ShapeAnnotationOptions.md#renderproperties)
***
### stroke?
> `optional` **stroke**: [`Stroke`](../../Drawing/classes/Stroke.md)
annotation stroke
#### Inherited from
[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`stroke`](ShapeAnnotationOptions.md#stroke)
***
### subject?
> `optional` **subject**: `string`
#### Inherited from
[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`subject`](ShapeAnnotationOptions.md#subject)
---
## Interface: FileAttachmentAnnotationOptions
Base options for all annotations
## Extends
- [`MarkupAnnotationOptions`](MarkupAnnotationOptions.md)
## Properties
### author?
> `optional` **author**: `string`
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`author`](MarkupAnnotationOptions.md#author)
***
### blendMode?
> `optional` **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
**`Experimental`**
blend mode
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`blendMode`](MarkupAnnotationOptions.md#blendmode)
***
### boundingBox?
> `optional` **boundingBox**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
#### Default Value
`null`
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`boundingBox`](MarkupAnnotationOptions.md#boundingbox)
***
### content?
> `optional` **content**: `string`
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
#### Default Value
`""`
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`content`](MarkupAnnotationOptions.md#content)
***
### dateModified?
> `optional` **dateModified**: `Date`
The date and time when the annotation was most recently modified.
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`dateModified`](MarkupAnnotationOptions.md#datemodified)
***
### icon?
> `optional` **icon**: [`FileAttachmentAnnotationIcon`](../enumerations/FileAttachmentAnnotationIcon.md)
icon
#### Default Value
`FileAttachmentAnnotationIcon.PushPin`
***
### opacity?
> `optional` **opacity**: `number`
**`Experimental`**
annotation opacity
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`opacity`](MarkupAnnotationOptions.md#opacity)
***
### page
> **page**: [`Page`](../../../classes/Page.md)
Page in which the annotation is embedded.
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`page`](MarkupAnnotationOptions.md#page)
***
### privateData?
> `optional` **privateData**: `object`
Custom data to be stored with the annotation
#### Default Value
`undefined`
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`privateData`](MarkupAnnotationOptions.md#privatedata)
***
### renderProperties?
> `optional` **renderProperties**: [`AnnotationRenderProperties`](../classes/AnnotationRenderProperties.md)
The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its rendering behaviors.
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`renderProperties`](MarkupAnnotationOptions.md#renderproperties)
***
### subject?
> `optional` **subject**: `string`
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`subject`](MarkupAnnotationOptions.md#subject)
---
## Interface: FreeTextAnnotationOptions
Base options for all annotations
## Extends
- [`MarkupAnnotationOptions`](MarkupAnnotationOptions.md)
## Properties
### author?
> `optional` **author**: `string`
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`author`](MarkupAnnotationOptions.md#author)
***
### backgroundColor?
> `optional` **backgroundColor**: `string`
***
### blendMode?
> `optional` **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
**`Experimental`**
blend mode
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`blendMode`](MarkupAnnotationOptions.md#blendmode)
***
### boundingBox?
> `optional` **boundingBox**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
#### Default Value
`null`
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`boundingBox`](MarkupAnnotationOptions.md#boundingbox)
***
### content?
> `optional` **content**: `string`
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
#### Default Value
`""`
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`content`](MarkupAnnotationOptions.md#content)
***
### dateModified?
> `optional` **dateModified**: `Date`
The date and time when the annotation was most recently modified.
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`dateModified`](MarkupAnnotationOptions.md#datemodified)
***
### opacity?
> `optional` **opacity**: `number`
**`Experimental`**
annotation opacity
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`opacity`](MarkupAnnotationOptions.md#opacity)
***
### page
> **page**: [`Page`](../../../classes/Page.md)
Page in which the annotation is embedded.
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`page`](MarkupAnnotationOptions.md#page)
***
### privateData?
> `optional` **privateData**: `object`
Custom data to be stored with the annotation
#### Default Value
`undefined`
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`privateData`](MarkupAnnotationOptions.md#privatedata)
***
### renderProperties?
> `optional` **renderProperties**: [`AnnotationRenderProperties`](../classes/AnnotationRenderProperties.md)
The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its rendering behaviors.
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`renderProperties`](MarkupAnnotationOptions.md#renderproperties)
***
### rotation?
> `optional` **rotation**: `number`
***
### subject?
> `optional` **subject**: `string`
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`subject`](MarkupAnnotationOptions.md#subject)
---
## Interface: ImageStampAnnotationOptions
An interface specific to image stamp annotations, defining the registered image used for creating the annotation.
## Properties
### image
> **image**: [`PdfImage`](../../../interfaces/PdfImage.md)
***
### subtype
> **subtype**: [`Image`](../enumerations/StampAnnotationSubtype.md#image)
---
## Interface: InkAnnotationOptions
Base options for all annotations
## Extends
- [`DrawingAnnotationOptions`](DrawingAnnotationOptions.md)
## Properties
### author?
> `optional` **author**: `string`
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`author`](DrawingAnnotationOptions.md#author)
***
### blendMode?
> `optional` **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
**`Experimental`**
blend mode
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`blendMode`](DrawingAnnotationOptions.md#blendmode)
***
### boundingBox?
> `optional` **boundingBox**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
#### Default Value
`null`
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`boundingBox`](DrawingAnnotationOptions.md#boundingbox)
***
### content?
> `optional` **content**: `string`
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
#### Default Value
`""`
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`content`](DrawingAnnotationOptions.md#content)
***
### dateModified?
> `optional` **dateModified**: `Date`
The date and time when the annotation was most recently modified.
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`dateModified`](DrawingAnnotationOptions.md#datemodified)
***
### opacity?
> `optional` **opacity**: `number`
**`Experimental`**
annotation opacity
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`opacity`](DrawingAnnotationOptions.md#opacity)
***
### page
> **page**: [`Page`](../../../classes/Page.md)
Page in which the annotation is embedded.
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`page`](DrawingAnnotationOptions.md#page)
***
### privateData?
> `optional` **privateData**: `object`
Custom data to be stored with the annotation
#### Default Value
`undefined`
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`privateData`](DrawingAnnotationOptions.md#privatedata)
***
### renderProperties?
> `optional` **renderProperties**: [`AnnotationRenderProperties`](../classes/AnnotationRenderProperties.md)
The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its rendering behaviors.
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`renderProperties`](DrawingAnnotationOptions.md#renderproperties)
***
### stroke?
> `optional` **stroke**: [`Stroke`](../../Drawing/classes/Stroke.md)
annotation stroke
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`stroke`](DrawingAnnotationOptions.md#stroke)
***
### subject?
> `optional` **subject**: `string`
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`subject`](DrawingAnnotationOptions.md#subject)
---
## Interface: InternalLinkAnnotationOptions
Base options for all annotations
## Extends
- [`AnnotationOptions`](AnnotationOptions.md)
## Properties
### boundingBox?
> `optional` **boundingBox**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
#### Default Value
`null`
#### Inherited from
[`AnnotationOptions`](AnnotationOptions.md).[`boundingBox`](AnnotationOptions.md#boundingbox)
***
### content?
> `optional` **content**: `string`
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
#### Default Value
`""`
#### Inherited from
[`AnnotationOptions`](AnnotationOptions.md).[`content`](AnnotationOptions.md#content)
***
### dateModified?
> `optional` **dateModified**: `Date`
The date and time when the annotation was most recently modified.
#### Inherited from
[`AnnotationOptions`](AnnotationOptions.md).[`dateModified`](AnnotationOptions.md#datemodified)
***
### destination
> **destination**: [`Destination`](../../../interfaces/Destination.md)
***
### page
> **page**: [`Page`](../../../classes/Page.md)
Page in which the annotation is embedded.
#### Inherited from
[`AnnotationOptions`](AnnotationOptions.md).[`page`](AnnotationOptions.md#page)
***
### privateData?
> `optional` **privateData**: `object`
Custom data to be stored with the annotation
#### Default Value
`undefined`
#### Inherited from
[`AnnotationOptions`](AnnotationOptions.md).[`privateData`](AnnotationOptions.md#privatedata)
***
### renderProperties?
> `optional` **renderProperties**: [`AnnotationRenderProperties`](../classes/AnnotationRenderProperties.md)
The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its rendering behaviors.
#### Inherited from
[`AnnotationOptions`](AnnotationOptions.md).[`renderProperties`](AnnotationOptions.md#renderproperties)
---
## Interface: LineAnnotationOptions
Base options for all annotations
## Extends
- [`DrawingAnnotationOptions`](DrawingAnnotationOptions.md)
## Properties
### author?
> `optional` **author**: `string`
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`author`](DrawingAnnotationOptions.md#author)
***
### blendMode?
> `optional` **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
**`Experimental`**
blend mode
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`blendMode`](DrawingAnnotationOptions.md#blendmode)
***
### boundingBox?
> `optional` **boundingBox**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
#### Default Value
`null`
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`boundingBox`](DrawingAnnotationOptions.md#boundingbox)
***
### color?
> `optional` **color**: [`RgbaColor`](../../Drawing/classes/RgbaColor.md)
***
### content?
> `optional` **content**: `string`
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
#### Default Value
`""`
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`content`](DrawingAnnotationOptions.md#content)
***
### dateModified?
> `optional` **dateModified**: `Date`
The date and time when the annotation was most recently modified.
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`dateModified`](DrawingAnnotationOptions.md#datemodified)
***
### endPoint?
> `optional` **endPoint**: `PdfPoint`
***
### lineEndingAtEnd?
> `optional` **lineEndingAtEnd**: [`LineEnding`](../../Drawing/enumerations/LineEnding.md)
***
### lineEndingAtStart?
> `optional` **lineEndingAtStart**: [`LineEnding`](../../Drawing/enumerations/LineEnding.md)
***
### lineWidth?
> `optional` **lineWidth**: `number`
***
### opacity?
> `optional` **opacity**: `number`
**`Experimental`**
annotation opacity
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`opacity`](DrawingAnnotationOptions.md#opacity)
***
### page
> **page**: [`Page`](../../../classes/Page.md)
Page in which the annotation is embedded.
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`page`](DrawingAnnotationOptions.md#page)
***
### privateData?
> `optional` **privateData**: `object`
Custom data to be stored with the annotation
#### Default Value
`undefined`
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`privateData`](DrawingAnnotationOptions.md#privatedata)
***
### renderProperties?
> `optional` **renderProperties**: [`AnnotationRenderProperties`](../classes/AnnotationRenderProperties.md)
The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its rendering behaviors.
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`renderProperties`](DrawingAnnotationOptions.md#renderproperties)
***
### startPoint?
> `optional` **startPoint**: `PdfPoint`
***
### stroke?
> `optional` **stroke**: [`Stroke`](../../Drawing/classes/Stroke.md)
annotation stroke
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`stroke`](DrawingAnnotationOptions.md#stroke)
***
### subject?
> `optional` **subject**: `string`
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`subject`](DrawingAnnotationOptions.md#subject)
---
## Interface: LinkAnnotationOptions
Base options for all annotations
## Extends
- [`AnnotationOptions`](AnnotationOptions.md)
## Properties
### boundingBox?
> `optional` **boundingBox**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
#### Default Value
`null`
#### Inherited from
[`AnnotationOptions`](AnnotationOptions.md).[`boundingBox`](AnnotationOptions.md#boundingbox)
***
### content?
> `optional` **content**: `string`
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
#### Default Value
`""`
#### Inherited from
[`AnnotationOptions`](AnnotationOptions.md).[`content`](AnnotationOptions.md#content)
***
### dateModified?
> `optional` **dateModified**: `Date`
The date and time when the annotation was most recently modified.
#### Inherited from
[`AnnotationOptions`](AnnotationOptions.md).[`dateModified`](AnnotationOptions.md#datemodified)
***
### page
> **page**: [`Page`](../../../classes/Page.md)
Page in which the annotation is embedded.
#### Inherited from
[`AnnotationOptions`](AnnotationOptions.md).[`page`](AnnotationOptions.md#page)
***
### privateData?
> `optional` **privateData**: `object`
Custom data to be stored with the annotation
#### Default Value
`undefined`
#### Inherited from
[`AnnotationOptions`](AnnotationOptions.md).[`privateData`](AnnotationOptions.md#privatedata)
***
### renderProperties?
> `optional` **renderProperties**: [`AnnotationRenderProperties`](../classes/AnnotationRenderProperties.md)
The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its rendering behaviors.
#### Inherited from
[`AnnotationOptions`](AnnotationOptions.md).[`renderProperties`](AnnotationOptions.md#renderproperties)
---
## Interface: MarkupAnnotationOptions
Base options for all annotations
## Extends
- [`AnnotationOptions`](AnnotationOptions.md)
## Extended by
- [`CaretAnnotationOptions`](CaretAnnotationOptions.md)
- [`DrawingAnnotationOptions`](DrawingAnnotationOptions.md)
- [`FileAttachmentAnnotationOptions`](FileAttachmentAnnotationOptions.md)
- [`FreeTextAnnotationOptions`](FreeTextAnnotationOptions.md)
- [`StampAnnotationOptions`](StampAnnotationOptions.md)
- [`TextMarkupAnnotationOptions`](TextMarkupAnnotationOptions.md)
## Properties
### author?
> `optional` **author**: `string`
***
### blendMode?
> `optional` **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
**`Experimental`**
blend mode
***
### boundingBox?
> `optional` **boundingBox**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
#### Default Value
`null`
#### Inherited from
[`AnnotationOptions`](AnnotationOptions.md).[`boundingBox`](AnnotationOptions.md#boundingbox)
***
### content?
> `optional` **content**: `string`
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
#### Default Value
`""`
#### Inherited from
[`AnnotationOptions`](AnnotationOptions.md).[`content`](AnnotationOptions.md#content)
***
### dateModified?
> `optional` **dateModified**: `Date`
The date and time when the annotation was most recently modified.
#### Inherited from
[`AnnotationOptions`](AnnotationOptions.md).[`dateModified`](AnnotationOptions.md#datemodified)
***
### opacity?
> `optional` **opacity**: `number`
**`Experimental`**
annotation opacity
***
### page
> **page**: [`Page`](../../../classes/Page.md)
Page in which the annotation is embedded.
#### Inherited from
[`AnnotationOptions`](AnnotationOptions.md).[`page`](AnnotationOptions.md#page)
***
### privateData?
> `optional` **privateData**: `object`
Custom data to be stored with the annotation
#### Default Value
`undefined`
#### Inherited from
[`AnnotationOptions`](AnnotationOptions.md).[`privateData`](AnnotationOptions.md#privatedata)
***
### renderProperties?
> `optional` **renderProperties**: [`AnnotationRenderProperties`](../classes/AnnotationRenderProperties.md)
The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its rendering behaviors.
#### Inherited from
[`AnnotationOptions`](AnnotationOptions.md).[`renderProperties`](AnnotationOptions.md#renderproperties)
***
### subject?
> `optional` **subject**: `string`
---
## Interface: NoteAnnotationOptions
Base options for all annotations
## Extends
- [`AnnotationOptions`](AnnotationOptions.md)
## Properties
### author?
> `optional` **author**: `string`
***
### blendMode?
> `optional` **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
**`Experimental`**
***
### boundingBox?
> `optional` **boundingBox**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
#### Default Value
`null`
#### Inherited from
[`AnnotationOptions`](AnnotationOptions.md).[`boundingBox`](AnnotationOptions.md#boundingbox)
***
### content?
> `optional` **content**: `string`
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
#### Default Value
`""`
#### Inherited from
[`AnnotationOptions`](AnnotationOptions.md).[`content`](AnnotationOptions.md#content)
***
### dateModified?
> `optional` **dateModified**: `Date`
The date and time when the annotation was most recently modified.
#### Inherited from
[`AnnotationOptions`](AnnotationOptions.md).[`dateModified`](AnnotationOptions.md#datemodified)
***
### fillColor?
> `optional` **fillColor**: `NoteAnnotationColor`
Represents the fill color of the annotation in hexadecimal representation.
#### Default Value
`"#FFECB3"`
***
### opacity?
> `optional` **opacity**: `number`
**`Experimental`**
***
### page
> **page**: [`Page`](../../../classes/Page.md)
Page in which the annotation is embedded.
#### Inherited from
[`AnnotationOptions`](AnnotationOptions.md).[`page`](AnnotationOptions.md#page)
***
### privateData?
> `optional` **privateData**: `object`
Custom data to be stored with the annotation
#### Default Value
`undefined`
#### Inherited from
[`AnnotationOptions`](AnnotationOptions.md).[`privateData`](AnnotationOptions.md#privatedata)
***
### renderProperties?
> `optional` **renderProperties**: [`AnnotationRenderProperties`](../classes/AnnotationRenderProperties.md)
The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its rendering behaviors.
#### Inherited from
[`AnnotationOptions`](AnnotationOptions.md).[`renderProperties`](AnnotationOptions.md#renderproperties)
***
### subject?
> `optional` **subject**: `string`
***
### topLeft
> **topLeft**: `PdfPoint`
Represents the top left point of the annotation on the page, specified as a `PdfPoint`.
#### Default Value
`new Point(0, 0) as PdfPoint`
---
## Interface: PdfStampAnnotationOptions
An interface specific to PDF stamp annotations, defining the registered PDF content (PDF page) used for creating the annotation.
## Properties
### pdfStamp
> **pdfStamp**: [`PdfContent`](../../Drawing/interfaces/PdfContent.md)
***
### subtype
> **subtype**: [`Pdf`](../enumerations/StampAnnotationSubtype.md#pdf)
---
## Interface: PolyLineAnnotationOptions
Base options for all annotations
## Extends
- [`DrawingAnnotationOptions`](DrawingAnnotationOptions.md)
## Properties
### author?
> `optional` **author**: `string`
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`author`](DrawingAnnotationOptions.md#author)
***
### blendMode?
> `optional` **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
**`Experimental`**
blend mode
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`blendMode`](DrawingAnnotationOptions.md#blendmode)
***
### boundingBox?
> `optional` **boundingBox**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
#### Default Value
`null`
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`boundingBox`](DrawingAnnotationOptions.md#boundingbox)
***
### content?
> `optional` **content**: `string`
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
#### Default Value
`""`
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`content`](DrawingAnnotationOptions.md#content)
***
### dateModified?
> `optional` **dateModified**: `Date`
The date and time when the annotation was most recently modified.
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`dateModified`](DrawingAnnotationOptions.md#datemodified)
***
### opacity?
> `optional` **opacity**: `number`
**`Experimental`**
annotation opacity
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`opacity`](DrawingAnnotationOptions.md#opacity)
***
### page
> **page**: [`Page`](../../../classes/Page.md)
Page in which the annotation is embedded.
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`page`](DrawingAnnotationOptions.md#page)
***
### privateData?
> `optional` **privateData**: `object`
Custom data to be stored with the annotation
#### Default Value
`undefined`
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`privateData`](DrawingAnnotationOptions.md#privatedata)
***
### renderProperties?
> `optional` **renderProperties**: [`AnnotationRenderProperties`](../classes/AnnotationRenderProperties.md)
The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its rendering behaviors.
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`renderProperties`](DrawingAnnotationOptions.md#renderproperties)
***
### stroke?
> `optional` **stroke**: [`Stroke`](../../Drawing/classes/Stroke.md)
annotation stroke
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`stroke`](DrawingAnnotationOptions.md#stroke)
***
### subject?
> `optional` **subject**: `string`
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`subject`](DrawingAnnotationOptions.md#subject)
---
## Interface: PolygonAnnotationOptions
## Extends
- [`ShapeAnnotationOptions`](ShapeAnnotationOptions.md)
## Properties
### author?
> `optional` **author**: `string`
#### Inherited from
[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`author`](ShapeAnnotationOptions.md#author)
***
### blendMode?
> `optional` **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
**`Experimental`**
blend mode
#### Inherited from
[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`blendMode`](ShapeAnnotationOptions.md#blendmode)
***
### boundingBox?
> `optional` **boundingBox**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
#### Default Value
`null`
#### Inherited from
[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`boundingBox`](ShapeAnnotationOptions.md#boundingbox)
***
### content?
> `optional` **content**: `string`
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
#### Default Value
`""`
#### Inherited from
[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`content`](ShapeAnnotationOptions.md#content)
***
### dateModified?
> `optional` **dateModified**: `Date`
The date and time when the annotation was most recently modified.
#### Inherited from
[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`dateModified`](ShapeAnnotationOptions.md#datemodified)
***
### fill?
> `optional` **fill**: `string`
annotation fill
#### Inherited from
[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`fill`](ShapeAnnotationOptions.md#fill)
***
### opacity?
> `optional` **opacity**: `number`
**`Experimental`**
annotation opacity
#### Inherited from
[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`opacity`](ShapeAnnotationOptions.md#opacity)
***
### page
> **page**: [`Page`](../../../classes/Page.md)
Page in which the annotation is embedded.
#### Inherited from
[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`page`](ShapeAnnotationOptions.md#page)
***
### privateData?
> `optional` **privateData**: `object`
Custom data to be stored with the annotation
#### Default Value
`undefined`
#### Inherited from
[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`privateData`](ShapeAnnotationOptions.md#privatedata)
***
### renderProperties?
> `optional` **renderProperties**: [`AnnotationRenderProperties`](../classes/AnnotationRenderProperties.md)
The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its rendering behaviors.
#### Inherited from
[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`renderProperties`](ShapeAnnotationOptions.md#renderproperties)
***
### stroke?
> `optional` **stroke**: [`Stroke`](../../Drawing/classes/Stroke.md)
annotation stroke
#### Inherited from
[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`stroke`](ShapeAnnotationOptions.md#stroke)
***
### subject?
> `optional` **subject**: `string`
#### Inherited from
[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`subject`](ShapeAnnotationOptions.md#subject)
---
## Interface: PredefinedTextStampAnnotationOptions
An interface specific to predefined text stamp annotations, defining the predefined text stamp type.
## Properties
### predefinedTextStampType
> **predefinedTextStampType**: [`PredefinedTextStampType`](../enumerations/PredefinedTextStampType.md)
***
### subtype
> **subtype**: [`PredefinedText`](../enumerations/StampAnnotationSubtype.md#predefinedtext)
---
## Interface: RectangleAnnotationOptions
## Extends
- [`ShapeAnnotationOptions`](ShapeAnnotationOptions.md)
## Properties
### author?
> `optional` **author**: `string`
#### Inherited from
[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`author`](ShapeAnnotationOptions.md#author)
***
### blendMode?
> `optional` **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
**`Experimental`**
blend mode
#### Inherited from
[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`blendMode`](ShapeAnnotationOptions.md#blendmode)
***
### boundingBox?
> `optional` **boundingBox**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
#### Default Value
`null`
#### Inherited from
[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`boundingBox`](ShapeAnnotationOptions.md#boundingbox)
***
### content?
> `optional` **content**: `string`
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
#### Default Value
`""`
#### Inherited from
[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`content`](ShapeAnnotationOptions.md#content)
***
### dateModified?
> `optional` **dateModified**: `Date`
The date and time when the annotation was most recently modified.
#### Inherited from
[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`dateModified`](ShapeAnnotationOptions.md#datemodified)
***
### fill?
> `optional` **fill**: `string`
annotation fill
#### Inherited from
[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`fill`](ShapeAnnotationOptions.md#fill)
***
### opacity?
> `optional` **opacity**: `number`
**`Experimental`**
annotation opacity
#### Inherited from
[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`opacity`](ShapeAnnotationOptions.md#opacity)
***
### page
> **page**: [`Page`](../../../classes/Page.md)
Page in which the annotation is embedded.
#### Inherited from
[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`page`](ShapeAnnotationOptions.md#page)
***
### privateData?
> `optional` **privateData**: `object`
Custom data to be stored with the annotation
#### Default Value
`undefined`
#### Inherited from
[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`privateData`](ShapeAnnotationOptions.md#privatedata)
***
### renderProperties?
> `optional` **renderProperties**: [`AnnotationRenderProperties`](../classes/AnnotationRenderProperties.md)
The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its rendering behaviors.
#### Inherited from
[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`renderProperties`](ShapeAnnotationOptions.md#renderproperties)
***
### stroke?
> `optional` **stroke**: [`Stroke`](../../Drawing/classes/Stroke.md)
annotation stroke
#### Inherited from
[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`stroke`](ShapeAnnotationOptions.md#stroke)
***
### subject?
> `optional` **subject**: `string`
#### Inherited from
[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`subject`](ShapeAnnotationOptions.md#subject)
---
## Interface: ShapeAnnotationOptions
## Extends
- [`DrawingAnnotationOptions`](DrawingAnnotationOptions.md)
## Extended by
- [`EllipseAnnotationOptions`](EllipseAnnotationOptions.md)
- [`PolygonAnnotationOptions`](PolygonAnnotationOptions.md)
- [`RectangleAnnotationOptions`](RectangleAnnotationOptions.md)
## Properties
### author?
> `optional` **author**: `string`
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`author`](DrawingAnnotationOptions.md#author)
***
### blendMode?
> `optional` **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
**`Experimental`**
blend mode
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`blendMode`](DrawingAnnotationOptions.md#blendmode)
***
### boundingBox?
> `optional` **boundingBox**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
#### Default Value
`null`
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`boundingBox`](DrawingAnnotationOptions.md#boundingbox)
***
### content?
> `optional` **content**: `string`
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
#### Default Value
`""`
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`content`](DrawingAnnotationOptions.md#content)
***
### dateModified?
> `optional` **dateModified**: `Date`
The date and time when the annotation was most recently modified.
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`dateModified`](DrawingAnnotationOptions.md#datemodified)
***
### fill?
> `optional` **fill**: `string`
annotation fill
***
### opacity?
> `optional` **opacity**: `number`
**`Experimental`**
annotation opacity
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`opacity`](DrawingAnnotationOptions.md#opacity)
***
### page
> **page**: [`Page`](../../../classes/Page.md)
Page in which the annotation is embedded.
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`page`](DrawingAnnotationOptions.md#page)
***
### privateData?
> `optional` **privateData**: `object`
Custom data to be stored with the annotation
#### Default Value
`undefined`
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`privateData`](DrawingAnnotationOptions.md#privatedata)
***
### renderProperties?
> `optional` **renderProperties**: [`AnnotationRenderProperties`](../classes/AnnotationRenderProperties.md)
The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its rendering behaviors.
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`renderProperties`](DrawingAnnotationOptions.md#renderproperties)
***
### stroke?
> `optional` **stroke**: [`Stroke`](../../Drawing/classes/Stroke.md)
annotation stroke
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`stroke`](DrawingAnnotationOptions.md#stroke)
***
### subject?
> `optional` **subject**: `string`
#### Inherited from
[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`subject`](DrawingAnnotationOptions.md#subject)
---
## Interface: StampAnnotationOptions
Base options for all annotations
## Extends
- [`MarkupAnnotationOptions`](MarkupAnnotationOptions.md)
## Properties
### author?
> `optional` **author**: `string`
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`author`](MarkupAnnotationOptions.md#author)
***
### blendMode?
> `optional` **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
**`Experimental`**
blend mode
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`blendMode`](MarkupAnnotationOptions.md#blendmode)
***
### boundingBox?
> `optional` **boundingBox**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
#### Default Value
`null`
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`boundingBox`](MarkupAnnotationOptions.md#boundingbox)
***
### content?
> `optional` **content**: `string`
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
#### Default Value
`""`
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`content`](MarkupAnnotationOptions.md#content)
***
### data
> **data**: [`StampData`](../type-aliases/StampData.md)
An object representing the stamp annotation data, which depends on the subtype.
***
### dateModified?
> `optional` **dateModified**: `Date`
The date and time when the annotation was most recently modified.
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`dateModified`](MarkupAnnotationOptions.md#datemodified)
***
### opacity?
> `optional` **opacity**: `number`
**`Experimental`**
annotation opacity
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`opacity`](MarkupAnnotationOptions.md#opacity)
***
### page
> **page**: [`Page`](../../../classes/Page.md)
Page in which the annotation is embedded.
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`page`](MarkupAnnotationOptions.md#page)
***
### privateData?
> `optional` **privateData**: `object`
Custom data to be stored with the annotation
#### Default Value
`undefined`
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`privateData`](MarkupAnnotationOptions.md#privatedata)
***
### renderProperties?
> `optional` **renderProperties**: [`AnnotationRenderProperties`](../classes/AnnotationRenderProperties.md)
The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its rendering behaviors.
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`renderProperties`](MarkupAnnotationOptions.md#renderproperties)
***
### subject?
> `optional` **subject**: `string`
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`subject`](MarkupAnnotationOptions.md#subject)
---
## Interface: TextMarkupAnnotationOptions
Interface representing options for text markup annotations.
This interface extends [MarkupAnnotationOptions](MarkupAnnotationOptions.md) and provides additional
properties specific to text markup annotations, such as the marked area,
annotation subtype, and fill color.
## Extends
- [`MarkupAnnotationOptions`](MarkupAnnotationOptions.md)
## Properties
### author?
> `optional` **author**: `string`
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`author`](MarkupAnnotationOptions.md#author)
***
### blendMode?
> `optional` **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)
**`Experimental`**
blend mode
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`blendMode`](MarkupAnnotationOptions.md#blendmode)
***
### boundingBox?
> `optional` **boundingBox**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
#### Default Value
`null`
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`boundingBox`](MarkupAnnotationOptions.md#boundingbox)
***
### content?
> `optional` **content**: `string`
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
#### Default Value
`""`
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`content`](MarkupAnnotationOptions.md#content)
***
### dateModified?
> `optional` **dateModified**: `Date`
The date and time when the annotation was most recently modified.
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`dateModified`](MarkupAnnotationOptions.md#datemodified)
***
### fillColor?
> `optional` **fillColor**: [`RgbColor`](../../Drawing/classes/RgbColor.md)
The color used to fill the marked-up area.
***
### opacity?
> `optional` **opacity**: `number`
**`Experimental`**
annotation opacity
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`opacity`](MarkupAnnotationOptions.md#opacity)
***
### page
> **page**: [`Page`](../../../classes/Page.md)
Page in which the annotation is embedded.
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`page`](MarkupAnnotationOptions.md#page)
***
### privateData?
> `optional` **privateData**: `object`
Custom data to be stored with the annotation
#### Default Value
`undefined`
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`privateData`](MarkupAnnotationOptions.md#privatedata)
***
### renderProperties?
> `optional` **renderProperties**: [`AnnotationRenderProperties`](../classes/AnnotationRenderProperties.md)
The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its rendering behaviors.
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`renderProperties`](MarkupAnnotationOptions.md#renderproperties)
***
### subject?
> `optional` **subject**: `string`
#### Inherited from
[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`subject`](MarkupAnnotationOptions.md#subject)
***
### subtype?
> `optional` **subtype**: `TextMarkupType`
Specifies the subtype of text markup annotation.
Determines how the text is visually marked, such as highlight, underline,
strikethrough, or squiggly.
***
### textMarkupArea?
> `optional` **textMarkupArea**: [`Quadrilateral`](../../Geometry/classes/Quadrilateral.md)\<`PdfPoint`\>[]
An array of quadrilateral regions defining the marked-up text area.
Each quadrilateral represents a portion of the text affected by the annotation.
---
## Interface: WatermarkAnnotationOptions
Base options for all annotations
## Extends
- [`AnnotationOptions`](AnnotationOptions.md)
## Properties
### boundingBox?
> `optional` **boundingBox**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
#### Default Value
`null`
#### Inherited from
[`AnnotationOptions`](AnnotationOptions.md).[`boundingBox`](AnnotationOptions.md#boundingbox)
***
### content?
> `optional` **content**: `string`
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
#### Default Value
`""`
#### Inherited from
[`AnnotationOptions`](AnnotationOptions.md).[`content`](AnnotationOptions.md#content)
***
### dateModified?
> `optional` **dateModified**: `Date`
The date and time when the annotation was most recently modified.
#### Inherited from
[`AnnotationOptions`](AnnotationOptions.md).[`dateModified`](AnnotationOptions.md#datemodified)
***
### page
> **page**: [`Page`](../../../classes/Page.md)
Page in which the annotation is embedded.
#### Inherited from
[`AnnotationOptions`](AnnotationOptions.md).[`page`](AnnotationOptions.md#page)
***
### privateData?
> `optional` **privateData**: `object`
Custom data to be stored with the annotation
#### Default Value
`undefined`
#### Inherited from
[`AnnotationOptions`](AnnotationOptions.md).[`privateData`](AnnotationOptions.md#privatedata)
***
### renderProperties?
> `optional` **renderProperties**: [`AnnotationRenderProperties`](../classes/AnnotationRenderProperties.md)
The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its rendering behaviors.
#### Inherited from
[`AnnotationOptions`](AnnotationOptions.md).[`renderProperties`](AnnotationOptions.md#renderproperties)
---
## Interface: WidgetAnnotationOptions
Base options for all annotations
## Extends
- [`AnnotationOptions`](AnnotationOptions.md)
## Properties
### boundingBox?
> `optional` **boundingBox**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
#### Default Value
`null`
#### Inherited from
[`AnnotationOptions`](AnnotationOptions.md).[`boundingBox`](AnnotationOptions.md#boundingbox)
***
### content?
> `optional` **content**: `string`
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
#### Default Value
`""`
#### Inherited from
[`AnnotationOptions`](AnnotationOptions.md).[`content`](AnnotationOptions.md#content)
***
### dateModified?
> `optional` **dateModified**: `Date`
The date and time when the annotation was most recently modified.
#### Inherited from
[`AnnotationOptions`](AnnotationOptions.md).[`dateModified`](AnnotationOptions.md#datemodified)
***
### page
> **page**: [`Page`](../../../classes/Page.md)
Page in which the annotation is embedded.
#### Inherited from
[`AnnotationOptions`](AnnotationOptions.md).[`page`](AnnotationOptions.md#page)
***
### privateData?
> `optional` **privateData**: `object`
Custom data to be stored with the annotation
#### Default Value
`undefined`
#### Inherited from
[`AnnotationOptions`](AnnotationOptions.md).[`privateData`](AnnotationOptions.md#privatedata)
***
### renderProperties?
> `optional` **renderProperties**: [`AnnotationRenderProperties`](../classes/AnnotationRenderProperties.md)
The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its rendering behaviors.
#### Inherited from
[`AnnotationOptions`](AnnotationOptions.md).[`renderProperties`](AnnotationOptions.md#renderproperties)
---
## Type Alias: StampData
> **StampData**: [`PredefinedTextStampAnnotationOptions`](../interfaces/PredefinedTextStampAnnotationOptions.md) \| [`CustomTextStampAnnotationOptions`](../interfaces/CustomTextStampAnnotationOptions.md) \| [`ImageStampAnnotationOptions`](../interfaces/ImageStampAnnotationOptions.md) \| [`PdfStampAnnotationOptions`](../interfaces/PdfStampAnnotationOptions.md) \| [`CustomStampAnnotationOptions`](../interfaces/CustomStampAnnotationOptions.md)
A type that represents stamp data, which can be one of the specific options for different subtypes.
---
## Class: Canvas
**`Experimental`**
Canvas for drawing grafics and text on a PdfPage
or a custom Annotation
## Constructors
### new Canvas()
> **new Canvas**(): [`Canvas`](Canvas.md)
**`Experimental`**
#### Returns
[`Canvas`](Canvas.md)
## Methods
### arcTo()
> **arcTo**(): `void`
**`Experimental`**
#### Returns
`void`
***
### beginPath()
> **beginPath**(): `void`
**`Experimental`**
#### Returns
`void`
***
### bezierCurveTo()
> **bezierCurveTo**(): `void`
**`Experimental`**
#### Returns
`void`
***
### drawText()
> **drawText**(): `void`
**`Experimental`**
#### Returns
`void`
***
### lineTo()
> **lineTo**(): `void`
**`Experimental`**
#### Returns
`void`
***
### moveTo()
> **moveTo**(): `void`
**`Experimental`**
#### Returns
`void`
---
## Class: Path
**`Experimental`**
## Constructors
### new Path()
> **new Path**(): [`Path`](Path.md)
**`Experimental`**
#### Returns
[`Path`](Path.md)
---
## Class: PdfContentCreator
**`Experimental`**
PdfContentCreator is used to generate content by using operations for drawing on canvas.
## Constructors
### new PdfContentCreator()
> **new PdfContentCreator**(`width`, `height`): [`PdfContentCreator`](PdfContentCreator.md)
**`Experimental`**
#### Parameters
• **width**: `number`
• **height**: `number`
#### Returns
[`PdfContentCreator`](PdfContentCreator.md)
## Methods
### beginPath()
> **beginPath**(): [`PdfContentCreator`](PdfContentCreator.md)
**`Experimental`**
#### Returns
[`PdfContentCreator`](PdfContentCreator.md)
***
### closePath()
> **closePath**(): [`PdfContentCreator`](PdfContentCreator.md)
**`Experimental`**
#### Returns
[`PdfContentCreator`](PdfContentCreator.md)
***
### drawImage()
#### drawImage(image, dx, dy)
> **drawImage**(`image`, `dx`, `dy`): [`PdfContentCreator`](PdfContentCreator.md)
**`Experimental`**
##### Parameters
• **image**: `Blob`
• **dx**: `number`
• **dy**: `number`
##### Returns
[`PdfContentCreator`](PdfContentCreator.md)
#### drawImage(image, dx, dy, dWidth, dHeight)
> **drawImage**(`image`, `dx`, `dy`, `dWidth`, `dHeight`): [`PdfContentCreator`](PdfContentCreator.md)
**`Experimental`**
##### Parameters
• **image**: `Blob`
• **dx**: `number`
• **dy**: `number`
• **dWidth**: `number`
• **dHeight**: `number`
##### Returns
[`PdfContentCreator`](PdfContentCreator.md)
#### drawImage(image, sx, sy, sWidth, sHeight, dx, dy, dWidth, dHeight)
> **drawImage**(`image`, `sx`, `sy`, `sWidth`, `sHeight`, `dx`, `dy`, `dWidth`, `dHeight`): [`PdfContentCreator`](PdfContentCreator.md)
**`Experimental`**
##### Parameters
• **image**: `Blob`
• **sx**: `number`
• **sy**: `number`
• **sWidth**: `number`
• **sHeight**: `number`
• **dx**: `number`
• **dy**: `number`
• **dWidth**: `number`
• **dHeight**: `number`
##### Returns
[`PdfContentCreator`](PdfContentCreator.md)
***
### generateContent()
> **generateContent**(): [`PdfContent`](../interfaces/PdfContent.md)
**`Experimental`**
#### Returns
[`PdfContent`](../interfaces/PdfContent.md)
***
### lineTo()
> **lineTo**(`x`, `y`): [`PdfContentCreator`](PdfContentCreator.md)
**`Experimental`**
#### Parameters
• **x**: `number`
• **y**: `number`
#### Returns
[`PdfContentCreator`](PdfContentCreator.md)
***
### moveTo()
> **moveTo**(`x`, `y`): [`PdfContentCreator`](PdfContentCreator.md)
**`Experimental`**
#### Parameters
• **x**: `number`
• **y**: `number`
#### Returns
[`PdfContentCreator`](PdfContentCreator.md)
***
### rotate()
> **rotate**(`deg`): [`PdfContentCreator`](PdfContentCreator.md)
**`Experimental`**
#### Parameters
• **deg**: `number`
#### Returns
[`PdfContentCreator`](PdfContentCreator.md)
***
### stroke()
> **stroke**(): [`PdfContentCreator`](PdfContentCreator.md)
**`Experimental`**
#### Returns
[`PdfContentCreator`](PdfContentCreator.md)
---
## Class: RgbColor
Represents a color with red, green and blue components.
## Extended by
- [`RgbaColor`](RgbaColor.md)
## Implements
- [`Cloneable`](../../../../Core/interfaces/Cloneable.md)\<[`RgbColor`](RgbColor.md)\>
## Constructors
### new RgbColor()
> **new RgbColor**(`colorString`): [`RgbColor`](RgbColor.md)
Creates a new RgbColor instance from a string representation (hex, rgb or hsl).
#### Parameters
• **colorString**: `string`
The string representation of the color.
#### Returns
[`RgbColor`](RgbColor.md)
#### Throws
If the input string is not a valid color representation.
### new RgbColor()
> **new RgbColor**(`r`?, `g`?, `b`?): [`RgbColor`](RgbColor.md)
Creates a new RgbColor instance.
#### Parameters
• **r?**: `number`
The red component of the color (0 to 255).
• **g?**: `number`
The green component of the color (0 to 255).
• **b?**: `number`
The blue component of the color (0 to 255).
#### Returns
[`RgbColor`](RgbColor.md)
## Properties
### b
> **b**: `number` = `0`
The blue component of the color (0 to 255).
***
### g
> **g**: `number` = `0`
The green component of the color (0 to 255).
***
### r
> **r**: `number` = `0`
The red component of the color (0 to 255).
## Accessors
### blue
> `get` **blue**(): `number`
The intensity of blue in the described color as a value 0-255.
#### Returns
`number`
***
### green
> `get` **green**(): `number`
The intensity of green in the described color as a value 0-255.
#### Returns
`number`
***
### red
> `get` **red**(): `number`
The intensity of red in the described color as a value 0-255.
#### Returns
`number`
## Methods
### clone()
> **clone**(): [`RgbColor`](RgbColor.md)
Creates a deep copy of the object.
#### Returns
[`RgbColor`](RgbColor.md)
A new instance that is a deep copy of the original object.
#### Implementation of
[`Cloneable`](../../../../Core/interfaces/Cloneable.md).[`clone`](../../../../Core/interfaces/Cloneable.md#clone)
***
### setRGB()
> **setRGB**(`red`, `green`, `blue`): `void`
Set a new color with all components at once
#### Parameters
• **red**: `number`
• **green**: `number`
• **blue**: `number`
#### Returns
`void`
***
### toHexString()
> **toHexString**(): `string`
Converts the color to a hexadecimal string
#### Returns
`string`
A string representation of the color in hexadecimal
#### Example
```ts
#330000
```
***
### toRgbString()
> **toRgbString**(): `string`
Converts the color to a CSS-formatted RGB string.
#### Returns
`string`
A string representation of the color in RGB format.
***
### toRgbaString()
> **toRgbaString**(): `string`
Converts the color to a CSS-formatted RGBA string.
#### Returns
`string`
A string representation of the color in RGBA format.
---
## Class: RgbaColor
Represents a color with red, green, blue, and alpha components.
## Extends
- [`RgbColor`](RgbColor.md)
## Implements
- [`Cloneable`](../../../../Core/interfaces/Cloneable.md)\<[`RgbaColor`](RgbaColor.md)\>
## Constructors
### new RgbaColor()
> **new RgbaColor**(`colorString`): [`RgbaColor`](RgbaColor.md)
Creates a new RgbaColor instance from a string representation (hex, rgb, rgba or hsl).
#### Parameters
• **colorString**: `string`
The string representation of the color.
#### Returns
[`RgbaColor`](RgbaColor.md)
#### Throws
If the input string is not a valid color representation.
#### Overrides
[`RgbColor`](RgbColor.md).[`constructor`](RgbColor.md#constructors)
### new RgbaColor()
> **new RgbaColor**(`r`?, `g`?, `b`?, `a`?): [`RgbaColor`](RgbaColor.md)
Creates a new RgbaColor instance.
#### Parameters
• **r?**: `number`
The red component of the color (0 to 255).
• **g?**: `number`
The green component of the color (0 to 255).
• **b?**: `number`
The blue component of the color (0 to 255).
• **a?**: `number`
The alpha (transparency) component of the color (0 to 1).
#### Returns
[`RgbaColor`](RgbaColor.md)
#### Overrides
[`RgbColor`](RgbColor.md).[`constructor`](RgbColor.md#constructors)
## Properties
### a
> **a**: `number`
The alpha component of the color (0 to 1).
***
### b
> **b**: `number` = `0`
The blue component of the color (0 to 255).
#### Inherited from
[`RgbColor`](RgbColor.md).[`b`](RgbColor.md#b)
***
### g
> **g**: `number` = `0`
The green component of the color (0 to 255).
#### Inherited from
[`RgbColor`](RgbColor.md).[`g`](RgbColor.md#g)
***
### r
> **r**: `number` = `0`
The red component of the color (0 to 255).
#### Inherited from
[`RgbColor`](RgbColor.md).[`r`](RgbColor.md#r)
## Accessors
### blue
> `get` **blue**(): `number`
The intensity of blue in the described color as a value 0-255.
#### Returns
`number`
#### Inherited from
[`RgbColor`](RgbColor.md).[`blue`](RgbColor.md#blue)
***
### green
> `get` **green**(): `number`
The intensity of green in the described color as a value 0-255.
#### Returns
`number`
#### Inherited from
[`RgbColor`](RgbColor.md).[`green`](RgbColor.md#green)
***
### red
> `get` **red**(): `number`
The intensity of red in the described color as a value 0-255.
#### Returns
`number`
#### Inherited from
[`RgbColor`](RgbColor.md).[`red`](RgbColor.md#red)
## Methods
### clone()
> **clone**(): [`RgbaColor`](RgbaColor.md)
Creates a deep copy of the object.
#### Returns
[`RgbaColor`](RgbaColor.md)
A new instance that is a deep copy of the original object.
#### Implementation of
[`Cloneable`](../../../../Core/interfaces/Cloneable.md).[`clone`](../../../../Core/interfaces/Cloneable.md#clone)
#### Overrides
[`RgbColor`](RgbColor.md).[`clone`](RgbColor.md#clone)
***
### setRGB()
> **setRGB**(`red`, `green`, `blue`): `void`
Set a new color with all components at once
#### Parameters
• **red**: `number`
• **green**: `number`
• **blue**: `number`
#### Returns
`void`
#### Inherited from
[`RgbColor`](RgbColor.md).[`setRGB`](RgbColor.md#setrgb)
***
### toHexString()
> **toHexString**(): `string`
Converts the color to a hexadecimal string
#### Returns
`string`
A string representation of the color in hexadecimal
#### Example
```ts
#330000
```
#### Inherited from
[`RgbColor`](RgbColor.md).[`toHexString`](RgbColor.md#tohexstring)
***
### toRgbString()
> **toRgbString**(): `string`
Converts the color to a CSS-formatted RGB string.
#### Returns
`string`
A string representation of the color in RGB format.
#### Inherited from
[`RgbColor`](RgbColor.md).[`toRgbString`](RgbColor.md#torgbstring)
***
### toRgbaString()
> **toRgbaString**(): `string`
Converts the color to a CSS-formatted RGBA string.
#### Returns
`string`
A string representation of the color in RGBA format.
#### Overrides
[`RgbColor`](RgbColor.md).[`toRgbaString`](RgbColor.md#torgbastring)
---
## Class: Stroke
**`Experimental`**
## Constructors
### new Stroke()
> **new Stroke**(): [`Stroke`](Stroke.md)
**`Experimental`**
#### Returns
[`Stroke`](Stroke.md)
## Properties
### color
> **color**: [`RgbaColor`](RgbaColor.md)
**`Experimental`**
The stroke color of the stroke. If the color is transparent, no stroke is visible.
***
### dashArray
> **dashArray**: `number`[] = `[]`
**`Experimental`**
A dash array defining a pattern of dashes and gaps to be used in drawing
***
### lineWidth
> **lineWidth**: `number` = `1`
**`Experimental`**
The stroke width in points. If this value is 0, no stroke is drawn.
#### Default Value
`1`
---
## Enumeration: BlendMode
Blend Mode controls how new content is painted and allows the new pixels to
be affected by what has already been drawn.
## Enumeration Members
### add
> **add**: `5`
Commonly used to create an animated lightening dissolve effect between two
images.
***
### darken
> **darken**: `2`
Replaces only the areas that are lighter than the blend color. Areas
darker than the blend color don’t change.
***
### lighten
> **lighten**: `3`
Replaces only pixels that are darker than the blend color. Areas lighter
than the blend color don’t change.
***
### multiply
> **multiply**: `1`
Multiplies the base color by the blend color, resulting in darker colors.
***
### normal
> **normal**: `0`
Applies color normally, with no interaction with the base colors.
***
### screen
> **screen**: `4`
Multiplies the inverse of the blend color by the base color, resulting in
a bleaching effect.
***
### subtract
> **subtract**: `6`
Commonly used to create an animated darkening dissolve effect between two
images.
---
## Enumeration: LineEnding
Line ending style controls how the end of a line is painted.
## Enumeration Members
### Butt
> **Butt**: `6`
(PDF 1.5) A short line at the endpoint perpendicular to the line itself
***
### Circle
> **Circle**: `4`
A circle filled with the annotation’s interior color, if any
***
### ClosedArrow
> **ClosedArrow**: `2`
Two short lines meeting in an acute angle as in the OpenArrow style and
connected by a third line to form a triangular closed arrowhead
filled with the annotation’s interior color, if any
***
### Diamond
> **Diamond**: `5`
A diamond shape filled with the annotation’s interior color, if any
***
### None
> **None**: `0`
No line ending
***
### OpenArrow
> **OpenArrow**: `1`
Two short lines meeting in an acute angle to form an open arrowhead
***
### ReversedClosedArrow
> **ReversedClosedArrow**: `8`
(PDF 1.5) A triangular closed arrowhead in the reverse direction from
ClosedArrow
***
### ReversedOpenArrow
> **ReversedOpenArrow**: `7`
(PDF 1.5) Two short lines in the reverse direction from OpenArrow
***
### Slash
> **Slash**: `9`
(PDF 1.6) A short line at the endpoint approximately 30 degrees clockwise
from perpendicular to the line itself
***
### Square
> **Square**: `3`
A square filled with the annotation’s interior color, if any
---
## Drawing
## Index
### Namespaces
- [Util](namespaces/Util/index.md)
### Enumerations
- [BlendMode](enumerations/BlendMode.md)
- [LineEnding](enumerations/LineEnding.md)
### Classes
- [Canvas](classes/Canvas.md)
- [Path](classes/Path.md)
- [PdfContentCreator](classes/PdfContentCreator.md)
- [RgbColor](classes/RgbColor.md)
- [RgbaColor](classes/RgbaColor.md)
- [Stroke](classes/Stroke.md)
### Interfaces
- [PdfContent](interfaces/PdfContent.md)
---
## Interface: PdfContent
**`Experimental`**
An interface representing PDF content.
---
## Function: drawLine()
> **drawLine**(`canvas`, `p1`, `p2`, `color`): `void`
Draws a line between two points on a canvas.
## Parameters
• **canvas**: `HTMLCanvasElement`
The canvas element on which to draw the line.
• **p1**: `DocumentViewPoint`
The starting point of the line.
• **p2**: `DocumentViewPoint`
The ending point of the line.
• **color**: `string`
The color of the line.
## Returns
`void`
---
## Function: drawPoint()
> **drawPoint**(`canvas`, `point`, `color`, `size`): `void`
Draws a point on a canvas.
## Parameters
• **canvas**: `HTMLCanvasElement`
The canvas element on which to draw the point.
• **point**: `DocumentViewPoint`
A `DocumentViewPoint` object representing the location of the point.
• **color**: `string`
The color of the point.
• **size**: `number`
The size (radius) of the point.
## Returns
`void`
---
## Function: drawQuadrilateralArea()
> **drawQuadrilateralArea**(`canvas`, `quadrilateral`, `color`): `void`
Draws a filled quadrilateral on a canvas.
## Parameters
• **canvas**: `HTMLCanvasElement`
The canvas element on which to draw the filled quadrilateral.
• **quadrilateral**: [`Quadrilateral`](../../../../Geometry/classes/Quadrilateral.md)\<`DocumentViewPoint`\>
A `Quadrilateral` object representing the vertices of the quadrilateral.
• **color**: `string`
The fill color of the quadrilateral.
## Returns
`void`
---
## Function: drawQuadrilateralOutline()
> **drawQuadrilateralOutline**(`canvas`, `quadrilateral`, `color`): `void`
Draws the outline of a quadrilateral on a canvas.
## Parameters
• **canvas**: `HTMLCanvasElement`
The canvas element on which to draw the quadrilateral outline.
• **quadrilateral**: [`Quadrilateral`](../../../../Geometry/classes/Quadrilateral.md)\<`DocumentViewPoint`\>
A `Quadrilateral` object representing the vertices of the quadrilateral.
• **color**: `string`
The color of the quadrilateral outline.
## Returns
`void`
---
## Util
## Index
### Functions
- [drawLine](functions/drawLine.md)
- [drawPoint](functions/drawPoint.md)
- [drawQuadrilateralArea](functions/drawQuadrilateralArea.md)
- [drawQuadrilateralOutline](functions/drawQuadrilateralOutline.md)
---
## Class: ButtonWidget
**`Experimental`**
A button widget annotation
## Extends
- [`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md)
## Constructors
### new ButtonWidget()
> **new ButtonWidget**(`options`): [`ButtonWidget`](ButtonWidget.md)
**`Experimental`**
#### Parameters
• **options**: [`WidgetAnnotationOptions`](../../Annotations/interfaces/WidgetAnnotationOptions.md)
Options used to initialize annotation.
#### Returns
[`ButtonWidget`](ButtonWidget.md)
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`constructor`](../../Annotations/classes/WidgetAnnotation.md#constructors)
## Properties
### action
> **action**: [`Action`](../../Actions/classes/Action.md)
**`Experimental`**
The action that is performed when the widget annotation is clicked on
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`action`](../../Annotations/classes/WidgetAnnotation.md#action)
## Accessors
### \_\_annotation
> `get` **\_\_annotation**(): `Annotation`
**`Experimental`**
> `set` **\_\_annotation**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: `Annotation`
#### Returns
`Annotation`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`__annotation`](../../Annotations/classes/WidgetAnnotation.md#__annotation)
***
### boundingBox
> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
**`Experimental`**
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
> `set` **boundingBox**(`rectangle`): `void`
**`Experimental`**
#### Parameters
• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Returns
[`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`boundingBox`](../../Annotations/classes/WidgetAnnotation.md#boundingbox)
***
### content
> `get` **content**(): `string`
**`Experimental`**
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
> `set` **content**(`content`): `void`
**`Experimental`**
#### Parameters
• **content**: `string`
#### Returns
`string`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`content`](../../Annotations/classes/WidgetAnnotation.md#content)
***
### dateModified
> `get` **dateModified**(): `Date`
**`Experimental`**
The date and time when the annotation was most recently modified.
> `set` **dateModified**(`date`): `void`
**`Experimental`**
#### Parameters
• **date**: `Date`
#### Returns
`Date`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`dateModified`](../../Annotations/classes/WidgetAnnotation.md#datemodified)
***
### hasChanges
> `get` **hasChanges**(): `boolean`
**`Experimental`**
Indicates if the annotation has been changed since the document was opened
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`hasChanges`](../../Annotations/classes/WidgetAnnotation.md#haschanges)
***
### hidden
> `get` **hidden**(): `boolean`
**`Experimental`**
If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user.
> `set` **hidden**(`hidden`): `void`
**`Experimental`**
#### Parameters
• **hidden**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`hidden`](../../Annotations/classes/WidgetAnnotation.md#hidden)
***
### id
> `get` **id**(): `void`
**`Experimental`**
A unique identifier for the annotation.
#### Returns
`void`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`id`](../../Annotations/classes/WidgetAnnotation.md#id)
***
### interactive
> `get` **interactive**(): `boolean`
**`Experimental`**
Specifies whether the annotation allows user interaction.
> `set` **interactive**(`interactive`): `void`
**`Experimental`**
#### Parameters
• **interactive**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`interactive`](../../Annotations/classes/WidgetAnnotation.md#interactive)
***
### isAdded
> `get` **isAdded**(): `boolean`
**`Experimental`**
Indicates whether the annotation was added to a page
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isAdded`](../../Annotations/classes/WidgetAnnotation.md#isadded)
***
### isMaintainingAspectRatio
> `get` **isMaintainingAspectRatio**(): `boolean`
**`Experimental`**
Indicates if the annotation is maintaining its aspect ratio
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isMaintainingAspectRatio`](../../Annotations/classes/WidgetAnnotation.md#ismaintainingaspectratio)
***
### isMarkupAnnotation
> `get` **isMarkupAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a markup annotation
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isMarkupAnnotation`](../../Annotations/classes/WidgetAnnotation.md#ismarkupannotation)
***
### isModified
> `get` **isModified**(): `boolean`
**`Experimental`**
Indicates if the annotation has changes that have not yet been saved to
the document
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isModified`](../../Annotations/classes/WidgetAnnotation.md#ismodified)
***
### isMoveable
> `get` **isMoveable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be moved by the user
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isMoveable`](../../Annotations/classes/WidgetAnnotation.md#ismoveable)
***
### isResizable
> `get` **isResizable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be resized by the user
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isResizable`](../../Annotations/classes/WidgetAnnotation.md#isresizable)
***
### isRotatable
> `get` **isRotatable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be rotated by the user
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isRotatable`](../../Annotations/classes/WidgetAnnotation.md#isrotatable)
***
### isSelectable
> `get` **isSelectable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be selected by the user
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isSelectable`](../../Annotations/classes/WidgetAnnotation.md#isselectable)
***
### isWidgetAnnotation
> `get` **isWidgetAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a widget annotation
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isWidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md#iswidgetannotation)
***
### locked
> `get` **locked**(): [`AnnotationLockedState`](../../Annotations/enumerations/AnnotationLockedState.md)
**`Experimental`**
Represents the locked state of the annotation.
> `set` **locked**(`locked`): `void`
**`Experimental`**
#### Parameters
• **locked**: [`AnnotationLockedState`](../../Annotations/enumerations/AnnotationLockedState.md)
#### Returns
[`AnnotationLockedState`](../../Annotations/enumerations/AnnotationLockedState.md)
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`locked`](../../Annotations/classes/WidgetAnnotation.md#locked)
***
### page
> `get` **page**(): [`Page`](../../../classes/Page.md)
**`Experimental`**
Page in which the annotation is embedded.
> `set` **page**(`page`): `void`
**`Experimental`**
Set the page in which the annotation is embedded.
#### Parameters
• **page**: [`Page`](../../../classes/Page.md)
The page to set as the annotation's page.
#### Returns
[`Page`](../../../classes/Page.md)
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`page`](../../Annotations/classes/WidgetAnnotation.md#page)
***
### pageNumber
> `get` **pageNumber**(): `number`
**`Experimental`**
Number of the page in which the annotation is embedded.
#### Returns
`number`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`pageNumber`](../../Annotations/classes/WidgetAnnotation.md#pagenumber)
***
### privateData
> `get` **privateData**(): `object`
**`Experimental`**
Custom data to be stored with the annotation
> `set` **privateData**(`privateData`): `void`
**`Experimental`**
#### Parameters
• **privateData**: `object`
#### Returns
`object`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`privateData`](../../Annotations/classes/WidgetAnnotation.md#privatedata)
***
### renderProperties
> `get` **renderProperties**(): [`AnnotationRenderProperties`](../../Annotations/classes/AnnotationRenderProperties.md)
**`Experimental`**
Object which encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its visibility, interactivity, and other rendering behaviors.
> `set` **renderProperties**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: [`AnnotationRenderProperties`](../../Annotations/classes/AnnotationRenderProperties.md)
#### Returns
[`AnnotationRenderProperties`](../../Annotations/classes/AnnotationRenderProperties.md)
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`renderProperties`](../../Annotations/classes/WidgetAnnotation.md#renderproperties)
***
### source
> `get` **source**(): `void`
**`Experimental`**
Tag that identifies the source the annotation is coming from, if
the source is an input PDF or an input FDF.
Newly created annotations always return `null`.
#### Returns
`void`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`source`](../../Annotations/classes/WidgetAnnotation.md#source)
***
### type
> `get` **type**(): [`AnnotationType`](../../Annotations/enumerations/AnnotationType.md)
**`Experimental`**
The PDF annotation type
#### Default Value
`AnnotationType.Widget`
#### Returns
[`AnnotationType`](../../Annotations/enumerations/AnnotationType.md)
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`type`](../../Annotations/classes/WidgetAnnotation.md#type)
## Methods
### dispose()
> **dispose**(): `void`
**`Experimental`**
#### Returns
`void`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`dispose`](../../Annotations/classes/WidgetAnnotation.md#dispose)
---
## Class: CheckBoxWidget
**`Experimental`**
A checkbox widget annotation
## Extends
- [`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md)
## Constructors
### new CheckBoxWidget()
> **new CheckBoxWidget**(`options`): [`CheckBoxWidget`](CheckBoxWidget.md)
**`Experimental`**
#### Parameters
• **options**: [`WidgetAnnotationOptions`](../../Annotations/interfaces/WidgetAnnotationOptions.md)
Options used to initialize annotation.
#### Returns
[`CheckBoxWidget`](CheckBoxWidget.md)
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`constructor`](../../Annotations/classes/WidgetAnnotation.md#constructors)
## Properties
### action
> **action**: [`Action`](../../Actions/classes/Action.md)
**`Experimental`**
The action that is performed when the widget annotation is clicked on
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`action`](../../Annotations/classes/WidgetAnnotation.md#action)
## Accessors
### \_\_annotation
> `get` **\_\_annotation**(): `Annotation`
**`Experimental`**
> `set` **\_\_annotation**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: `Annotation`
#### Returns
`Annotation`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`__annotation`](../../Annotations/classes/WidgetAnnotation.md#__annotation)
***
### boundingBox
> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
**`Experimental`**
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
> `set` **boundingBox**(`rectangle`): `void`
**`Experimental`**
#### Parameters
• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Returns
[`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`boundingBox`](../../Annotations/classes/WidgetAnnotation.md#boundingbox)
***
### content
> `get` **content**(): `string`
**`Experimental`**
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
> `set` **content**(`content`): `void`
**`Experimental`**
#### Parameters
• **content**: `string`
#### Returns
`string`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`content`](../../Annotations/classes/WidgetAnnotation.md#content)
***
### dateModified
> `get` **dateModified**(): `Date`
**`Experimental`**
The date and time when the annotation was most recently modified.
> `set` **dateModified**(`date`): `void`
**`Experimental`**
#### Parameters
• **date**: `Date`
#### Returns
`Date`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`dateModified`](../../Annotations/classes/WidgetAnnotation.md#datemodified)
***
### hasChanges
> `get` **hasChanges**(): `boolean`
**`Experimental`**
Indicates if the annotation has been changed since the document was opened
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`hasChanges`](../../Annotations/classes/WidgetAnnotation.md#haschanges)
***
### hidden
> `get` **hidden**(): `boolean`
**`Experimental`**
If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user.
> `set` **hidden**(`hidden`): `void`
**`Experimental`**
#### Parameters
• **hidden**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`hidden`](../../Annotations/classes/WidgetAnnotation.md#hidden)
***
### id
> `get` **id**(): `void`
**`Experimental`**
A unique identifier for the annotation.
#### Returns
`void`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`id`](../../Annotations/classes/WidgetAnnotation.md#id)
***
### interactive
> `get` **interactive**(): `boolean`
**`Experimental`**
Specifies whether the annotation allows user interaction.
> `set` **interactive**(`interactive`): `void`
**`Experimental`**
#### Parameters
• **interactive**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`interactive`](../../Annotations/classes/WidgetAnnotation.md#interactive)
***
### isAdded
> `get` **isAdded**(): `boolean`
**`Experimental`**
Indicates whether the annotation was added to a page
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isAdded`](../../Annotations/classes/WidgetAnnotation.md#isadded)
***
### isMaintainingAspectRatio
> `get` **isMaintainingAspectRatio**(): `boolean`
**`Experimental`**
Indicates if the annotation is maintaining its aspect ratio
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isMaintainingAspectRatio`](../../Annotations/classes/WidgetAnnotation.md#ismaintainingaspectratio)
***
### isMarkupAnnotation
> `get` **isMarkupAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a markup annotation
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isMarkupAnnotation`](../../Annotations/classes/WidgetAnnotation.md#ismarkupannotation)
***
### isModified
> `get` **isModified**(): `boolean`
**`Experimental`**
Indicates if the annotation has changes that have not yet been saved to
the document
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isModified`](../../Annotations/classes/WidgetAnnotation.md#ismodified)
***
### isMoveable
> `get` **isMoveable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be moved by the user
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isMoveable`](../../Annotations/classes/WidgetAnnotation.md#ismoveable)
***
### isResizable
> `get` **isResizable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be resized by the user
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isResizable`](../../Annotations/classes/WidgetAnnotation.md#isresizable)
***
### isRotatable
> `get` **isRotatable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be rotated by the user
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isRotatable`](../../Annotations/classes/WidgetAnnotation.md#isrotatable)
***
### isSelectable
> `get` **isSelectable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be selected by the user
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isSelectable`](../../Annotations/classes/WidgetAnnotation.md#isselectable)
***
### isWidgetAnnotation
> `get` **isWidgetAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a widget annotation
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isWidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md#iswidgetannotation)
***
### locked
> `get` **locked**(): [`AnnotationLockedState`](../../Annotations/enumerations/AnnotationLockedState.md)
**`Experimental`**
Represents the locked state of the annotation.
> `set` **locked**(`locked`): `void`
**`Experimental`**
#### Parameters
• **locked**: [`AnnotationLockedState`](../../Annotations/enumerations/AnnotationLockedState.md)
#### Returns
[`AnnotationLockedState`](../../Annotations/enumerations/AnnotationLockedState.md)
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`locked`](../../Annotations/classes/WidgetAnnotation.md#locked)
***
### page
> `get` **page**(): [`Page`](../../../classes/Page.md)
**`Experimental`**
Page in which the annotation is embedded.
> `set` **page**(`page`): `void`
**`Experimental`**
Set the page in which the annotation is embedded.
#### Parameters
• **page**: [`Page`](../../../classes/Page.md)
The page to set as the annotation's page.
#### Returns
[`Page`](../../../classes/Page.md)
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`page`](../../Annotations/classes/WidgetAnnotation.md#page)
***
### pageNumber
> `get` **pageNumber**(): `number`
**`Experimental`**
Number of the page in which the annotation is embedded.
#### Returns
`number`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`pageNumber`](../../Annotations/classes/WidgetAnnotation.md#pagenumber)
***
### privateData
> `get` **privateData**(): `object`
**`Experimental`**
Custom data to be stored with the annotation
> `set` **privateData**(`privateData`): `void`
**`Experimental`**
#### Parameters
• **privateData**: `object`
#### Returns
`object`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`privateData`](../../Annotations/classes/WidgetAnnotation.md#privatedata)
***
### renderProperties
> `get` **renderProperties**(): [`AnnotationRenderProperties`](../../Annotations/classes/AnnotationRenderProperties.md)
**`Experimental`**
Object which encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its visibility, interactivity, and other rendering behaviors.
> `set` **renderProperties**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: [`AnnotationRenderProperties`](../../Annotations/classes/AnnotationRenderProperties.md)
#### Returns
[`AnnotationRenderProperties`](../../Annotations/classes/AnnotationRenderProperties.md)
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`renderProperties`](../../Annotations/classes/WidgetAnnotation.md#renderproperties)
***
### source
> `get` **source**(): `void`
**`Experimental`**
Tag that identifies the source the annotation is coming from, if
the source is an input PDF or an input FDF.
Newly created annotations always return `null`.
#### Returns
`void`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`source`](../../Annotations/classes/WidgetAnnotation.md#source)
***
### type
> `get` **type**(): [`AnnotationType`](../../Annotations/enumerations/AnnotationType.md)
**`Experimental`**
The PDF annotation type
#### Default Value
`AnnotationType.Widget`
#### Returns
[`AnnotationType`](../../Annotations/enumerations/AnnotationType.md)
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`type`](../../Annotations/classes/WidgetAnnotation.md#type)
## Methods
### dispose()
> **dispose**(): `void`
**`Experimental`**
#### Returns
`void`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`dispose`](../../Annotations/classes/WidgetAnnotation.md#dispose)
---
## Class: ComboBoxWidget
**`Experimental`**
A combo box widget annotation
## Extends
- [`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md)
## Constructors
### new ComboBoxWidget()
> **new ComboBoxWidget**(`options`): [`ComboBoxWidget`](ComboBoxWidget.md)
**`Experimental`**
#### Parameters
• **options**: [`WidgetAnnotationOptions`](../../Annotations/interfaces/WidgetAnnotationOptions.md)
Options used to initialize annotation.
#### Returns
[`ComboBoxWidget`](ComboBoxWidget.md)
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`constructor`](../../Annotations/classes/WidgetAnnotation.md#constructors)
## Properties
### action
> **action**: [`Action`](../../Actions/classes/Action.md)
**`Experimental`**
The action that is performed when the widget annotation is clicked on
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`action`](../../Annotations/classes/WidgetAnnotation.md#action)
## Accessors
### \_\_annotation
> `get` **\_\_annotation**(): `Annotation`
**`Experimental`**
> `set` **\_\_annotation**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: `Annotation`
#### Returns
`Annotation`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`__annotation`](../../Annotations/classes/WidgetAnnotation.md#__annotation)
***
### boundingBox
> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
**`Experimental`**
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
> `set` **boundingBox**(`rectangle`): `void`
**`Experimental`**
#### Parameters
• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Returns
[`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`boundingBox`](../../Annotations/classes/WidgetAnnotation.md#boundingbox)
***
### content
> `get` **content**(): `string`
**`Experimental`**
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
> `set` **content**(`content`): `void`
**`Experimental`**
#### Parameters
• **content**: `string`
#### Returns
`string`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`content`](../../Annotations/classes/WidgetAnnotation.md#content)
***
### dateModified
> `get` **dateModified**(): `Date`
**`Experimental`**
The date and time when the annotation was most recently modified.
> `set` **dateModified**(`date`): `void`
**`Experimental`**
#### Parameters
• **date**: `Date`
#### Returns
`Date`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`dateModified`](../../Annotations/classes/WidgetAnnotation.md#datemodified)
***
### hasChanges
> `get` **hasChanges**(): `boolean`
**`Experimental`**
Indicates if the annotation has been changed since the document was opened
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`hasChanges`](../../Annotations/classes/WidgetAnnotation.md#haschanges)
***
### hidden
> `get` **hidden**(): `boolean`
**`Experimental`**
If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user.
> `set` **hidden**(`hidden`): `void`
**`Experimental`**
#### Parameters
• **hidden**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`hidden`](../../Annotations/classes/WidgetAnnotation.md#hidden)
***
### id
> `get` **id**(): `void`
**`Experimental`**
A unique identifier for the annotation.
#### Returns
`void`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`id`](../../Annotations/classes/WidgetAnnotation.md#id)
***
### interactive
> `get` **interactive**(): `boolean`
**`Experimental`**
Specifies whether the annotation allows user interaction.
> `set` **interactive**(`interactive`): `void`
**`Experimental`**
#### Parameters
• **interactive**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`interactive`](../../Annotations/classes/WidgetAnnotation.md#interactive)
***
### isAdded
> `get` **isAdded**(): `boolean`
**`Experimental`**
Indicates whether the annotation was added to a page
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isAdded`](../../Annotations/classes/WidgetAnnotation.md#isadded)
***
### isMaintainingAspectRatio
> `get` **isMaintainingAspectRatio**(): `boolean`
**`Experimental`**
Indicates if the annotation is maintaining its aspect ratio
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isMaintainingAspectRatio`](../../Annotations/classes/WidgetAnnotation.md#ismaintainingaspectratio)
***
### isMarkupAnnotation
> `get` **isMarkupAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a markup annotation
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isMarkupAnnotation`](../../Annotations/classes/WidgetAnnotation.md#ismarkupannotation)
***
### isModified
> `get` **isModified**(): `boolean`
**`Experimental`**
Indicates if the annotation has changes that have not yet been saved to
the document
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isModified`](../../Annotations/classes/WidgetAnnotation.md#ismodified)
***
### isMoveable
> `get` **isMoveable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be moved by the user
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isMoveable`](../../Annotations/classes/WidgetAnnotation.md#ismoveable)
***
### isResizable
> `get` **isResizable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be resized by the user
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isResizable`](../../Annotations/classes/WidgetAnnotation.md#isresizable)
***
### isRotatable
> `get` **isRotatable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be rotated by the user
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isRotatable`](../../Annotations/classes/WidgetAnnotation.md#isrotatable)
***
### isSelectable
> `get` **isSelectable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be selected by the user
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isSelectable`](../../Annotations/classes/WidgetAnnotation.md#isselectable)
***
### isWidgetAnnotation
> `get` **isWidgetAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a widget annotation
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isWidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md#iswidgetannotation)
***
### locked
> `get` **locked**(): [`AnnotationLockedState`](../../Annotations/enumerations/AnnotationLockedState.md)
**`Experimental`**
Represents the locked state of the annotation.
> `set` **locked**(`locked`): `void`
**`Experimental`**
#### Parameters
• **locked**: [`AnnotationLockedState`](../../Annotations/enumerations/AnnotationLockedState.md)
#### Returns
[`AnnotationLockedState`](../../Annotations/enumerations/AnnotationLockedState.md)
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`locked`](../../Annotations/classes/WidgetAnnotation.md#locked)
***
### page
> `get` **page**(): [`Page`](../../../classes/Page.md)
**`Experimental`**
Page in which the annotation is embedded.
> `set` **page**(`page`): `void`
**`Experimental`**
Set the page in which the annotation is embedded.
#### Parameters
• **page**: [`Page`](../../../classes/Page.md)
The page to set as the annotation's page.
#### Returns
[`Page`](../../../classes/Page.md)
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`page`](../../Annotations/classes/WidgetAnnotation.md#page)
***
### pageNumber
> `get` **pageNumber**(): `number`
**`Experimental`**
Number of the page in which the annotation is embedded.
#### Returns
`number`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`pageNumber`](../../Annotations/classes/WidgetAnnotation.md#pagenumber)
***
### privateData
> `get` **privateData**(): `object`
**`Experimental`**
Custom data to be stored with the annotation
> `set` **privateData**(`privateData`): `void`
**`Experimental`**
#### Parameters
• **privateData**: `object`
#### Returns
`object`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`privateData`](../../Annotations/classes/WidgetAnnotation.md#privatedata)
***
### renderProperties
> `get` **renderProperties**(): [`AnnotationRenderProperties`](../../Annotations/classes/AnnotationRenderProperties.md)
**`Experimental`**
Object which encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its visibility, interactivity, and other rendering behaviors.
> `set` **renderProperties**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: [`AnnotationRenderProperties`](../../Annotations/classes/AnnotationRenderProperties.md)
#### Returns
[`AnnotationRenderProperties`](../../Annotations/classes/AnnotationRenderProperties.md)
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`renderProperties`](../../Annotations/classes/WidgetAnnotation.md#renderproperties)
***
### source
> `get` **source**(): `void`
**`Experimental`**
Tag that identifies the source the annotation is coming from, if
the source is an input PDF or an input FDF.
Newly created annotations always return `null`.
#### Returns
`void`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`source`](../../Annotations/classes/WidgetAnnotation.md#source)
***
### type
> `get` **type**(): [`AnnotationType`](../../Annotations/enumerations/AnnotationType.md)
**`Experimental`**
The PDF annotation type
#### Default Value
`AnnotationType.Widget`
#### Returns
[`AnnotationType`](../../Annotations/enumerations/AnnotationType.md)
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`type`](../../Annotations/classes/WidgetAnnotation.md#type)
## Methods
### dispose()
> **dispose**(): `void`
**`Experimental`**
#### Returns
`void`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`dispose`](../../Annotations/classes/WidgetAnnotation.md#dispose)
---
## Class: FormWidget
**`Experimental`**
A form widget annotation
## Extends
- [`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md)
## Constructors
### new FormWidget()
> **new FormWidget**(`options`): [`FormWidget`](FormWidget.md)
**`Experimental`**
#### Parameters
• **options**: [`WidgetAnnotationOptions`](../../Annotations/interfaces/WidgetAnnotationOptions.md)
Options used to initialize annotation.
#### Returns
[`FormWidget`](FormWidget.md)
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`constructor`](../../Annotations/classes/WidgetAnnotation.md#constructors)
## Properties
### action
> **action**: [`Action`](../../Actions/classes/Action.md)
**`Experimental`**
The action that is performed when the widget annotation is clicked on
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`action`](../../Annotations/classes/WidgetAnnotation.md#action)
## Accessors
### \_\_annotation
> `get` **\_\_annotation**(): `Annotation`
**`Experimental`**
> `set` **\_\_annotation**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: `Annotation`
#### Returns
`Annotation`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`__annotation`](../../Annotations/classes/WidgetAnnotation.md#__annotation)
***
### boundingBox
> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
**`Experimental`**
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
> `set` **boundingBox**(`rectangle`): `void`
**`Experimental`**
#### Parameters
• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Returns
[`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`boundingBox`](../../Annotations/classes/WidgetAnnotation.md#boundingbox)
***
### content
> `get` **content**(): `string`
**`Experimental`**
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
> `set` **content**(`content`): `void`
**`Experimental`**
#### Parameters
• **content**: `string`
#### Returns
`string`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`content`](../../Annotations/classes/WidgetAnnotation.md#content)
***
### dateModified
> `get` **dateModified**(): `Date`
**`Experimental`**
The date and time when the annotation was most recently modified.
> `set` **dateModified**(`date`): `void`
**`Experimental`**
#### Parameters
• **date**: `Date`
#### Returns
`Date`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`dateModified`](../../Annotations/classes/WidgetAnnotation.md#datemodified)
***
### hasChanges
> `get` **hasChanges**(): `boolean`
**`Experimental`**
Indicates if the annotation has been changed since the document was opened
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`hasChanges`](../../Annotations/classes/WidgetAnnotation.md#haschanges)
***
### hidden
> `get` **hidden**(): `boolean`
**`Experimental`**
If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user.
> `set` **hidden**(`hidden`): `void`
**`Experimental`**
#### Parameters
• **hidden**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`hidden`](../../Annotations/classes/WidgetAnnotation.md#hidden)
***
### id
> `get` **id**(): `void`
**`Experimental`**
A unique identifier for the annotation.
#### Returns
`void`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`id`](../../Annotations/classes/WidgetAnnotation.md#id)
***
### interactive
> `get` **interactive**(): `boolean`
**`Experimental`**
Specifies whether the annotation allows user interaction.
> `set` **interactive**(`interactive`): `void`
**`Experimental`**
#### Parameters
• **interactive**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`interactive`](../../Annotations/classes/WidgetAnnotation.md#interactive)
***
### isAdded
> `get` **isAdded**(): `boolean`
**`Experimental`**
Indicates whether the annotation was added to a page
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isAdded`](../../Annotations/classes/WidgetAnnotation.md#isadded)
***
### isMaintainingAspectRatio
> `get` **isMaintainingAspectRatio**(): `boolean`
**`Experimental`**
Indicates if the annotation is maintaining its aspect ratio
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isMaintainingAspectRatio`](../../Annotations/classes/WidgetAnnotation.md#ismaintainingaspectratio)
***
### isMarkupAnnotation
> `get` **isMarkupAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a markup annotation
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isMarkupAnnotation`](../../Annotations/classes/WidgetAnnotation.md#ismarkupannotation)
***
### isModified
> `get` **isModified**(): `boolean`
**`Experimental`**
Indicates if the annotation has changes that have not yet been saved to
the document
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isModified`](../../Annotations/classes/WidgetAnnotation.md#ismodified)
***
### isMoveable
> `get` **isMoveable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be moved by the user
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isMoveable`](../../Annotations/classes/WidgetAnnotation.md#ismoveable)
***
### isResizable
> `get` **isResizable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be resized by the user
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isResizable`](../../Annotations/classes/WidgetAnnotation.md#isresizable)
***
### isRotatable
> `get` **isRotatable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be rotated by the user
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isRotatable`](../../Annotations/classes/WidgetAnnotation.md#isrotatable)
***
### isSelectable
> `get` **isSelectable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be selected by the user
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isSelectable`](../../Annotations/classes/WidgetAnnotation.md#isselectable)
***
### isWidgetAnnotation
> `get` **isWidgetAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a widget annotation
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isWidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md#iswidgetannotation)
***
### locked
> `get` **locked**(): [`AnnotationLockedState`](../../Annotations/enumerations/AnnotationLockedState.md)
**`Experimental`**
Represents the locked state of the annotation.
> `set` **locked**(`locked`): `void`
**`Experimental`**
#### Parameters
• **locked**: [`AnnotationLockedState`](../../Annotations/enumerations/AnnotationLockedState.md)
#### Returns
[`AnnotationLockedState`](../../Annotations/enumerations/AnnotationLockedState.md)
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`locked`](../../Annotations/classes/WidgetAnnotation.md#locked)
***
### page
> `get` **page**(): [`Page`](../../../classes/Page.md)
**`Experimental`**
Page in which the annotation is embedded.
> `set` **page**(`page`): `void`
**`Experimental`**
Set the page in which the annotation is embedded.
#### Parameters
• **page**: [`Page`](../../../classes/Page.md)
The page to set as the annotation's page.
#### Returns
[`Page`](../../../classes/Page.md)
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`page`](../../Annotations/classes/WidgetAnnotation.md#page)
***
### pageNumber
> `get` **pageNumber**(): `number`
**`Experimental`**
Number of the page in which the annotation is embedded.
#### Returns
`number`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`pageNumber`](../../Annotations/classes/WidgetAnnotation.md#pagenumber)
***
### privateData
> `get` **privateData**(): `object`
**`Experimental`**
Custom data to be stored with the annotation
> `set` **privateData**(`privateData`): `void`
**`Experimental`**
#### Parameters
• **privateData**: `object`
#### Returns
`object`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`privateData`](../../Annotations/classes/WidgetAnnotation.md#privatedata)
***
### renderProperties
> `get` **renderProperties**(): [`AnnotationRenderProperties`](../../Annotations/classes/AnnotationRenderProperties.md)
**`Experimental`**
Object which encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its visibility, interactivity, and other rendering behaviors.
> `set` **renderProperties**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: [`AnnotationRenderProperties`](../../Annotations/classes/AnnotationRenderProperties.md)
#### Returns
[`AnnotationRenderProperties`](../../Annotations/classes/AnnotationRenderProperties.md)
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`renderProperties`](../../Annotations/classes/WidgetAnnotation.md#renderproperties)
***
### source
> `get` **source**(): `void`
**`Experimental`**
Tag that identifies the source the annotation is coming from, if
the source is an input PDF or an input FDF.
Newly created annotations always return `null`.
#### Returns
`void`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`source`](../../Annotations/classes/WidgetAnnotation.md#source)
***
### type
> `get` **type**(): [`AnnotationType`](../../Annotations/enumerations/AnnotationType.md)
**`Experimental`**
The PDF annotation type
#### Default Value
`AnnotationType.Widget`
#### Returns
[`AnnotationType`](../../Annotations/enumerations/AnnotationType.md)
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`type`](../../Annotations/classes/WidgetAnnotation.md#type)
## Methods
### dispose()
> **dispose**(): `void`
**`Experimental`**
#### Returns
`void`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`dispose`](../../Annotations/classes/WidgetAnnotation.md#dispose)
---
## Class: ListBoxWidget
**`Experimental`**
A list box widget annotation
## Extends
- [`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md)
## Constructors
### new ListBoxWidget()
> **new ListBoxWidget**(`options`): [`ListBoxWidget`](ListBoxWidget.md)
**`Experimental`**
#### Parameters
• **options**: [`WidgetAnnotationOptions`](../../Annotations/interfaces/WidgetAnnotationOptions.md)
Options used to initialize annotation.
#### Returns
[`ListBoxWidget`](ListBoxWidget.md)
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`constructor`](../../Annotations/classes/WidgetAnnotation.md#constructors)
## Properties
### action
> **action**: [`Action`](../../Actions/classes/Action.md)
**`Experimental`**
The action that is performed when the widget annotation is clicked on
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`action`](../../Annotations/classes/WidgetAnnotation.md#action)
## Accessors
### \_\_annotation
> `get` **\_\_annotation**(): `Annotation`
**`Experimental`**
> `set` **\_\_annotation**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: `Annotation`
#### Returns
`Annotation`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`__annotation`](../../Annotations/classes/WidgetAnnotation.md#__annotation)
***
### boundingBox
> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
**`Experimental`**
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
> `set` **boundingBox**(`rectangle`): `void`
**`Experimental`**
#### Parameters
• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Returns
[`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`boundingBox`](../../Annotations/classes/WidgetAnnotation.md#boundingbox)
***
### content
> `get` **content**(): `string`
**`Experimental`**
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
> `set` **content**(`content`): `void`
**`Experimental`**
#### Parameters
• **content**: `string`
#### Returns
`string`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`content`](../../Annotations/classes/WidgetAnnotation.md#content)
***
### dateModified
> `get` **dateModified**(): `Date`
**`Experimental`**
The date and time when the annotation was most recently modified.
> `set` **dateModified**(`date`): `void`
**`Experimental`**
#### Parameters
• **date**: `Date`
#### Returns
`Date`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`dateModified`](../../Annotations/classes/WidgetAnnotation.md#datemodified)
***
### hasChanges
> `get` **hasChanges**(): `boolean`
**`Experimental`**
Indicates if the annotation has been changed since the document was opened
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`hasChanges`](../../Annotations/classes/WidgetAnnotation.md#haschanges)
***
### hidden
> `get` **hidden**(): `boolean`
**`Experimental`**
If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user.
> `set` **hidden**(`hidden`): `void`
**`Experimental`**
#### Parameters
• **hidden**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`hidden`](../../Annotations/classes/WidgetAnnotation.md#hidden)
***
### id
> `get` **id**(): `void`
**`Experimental`**
A unique identifier for the annotation.
#### Returns
`void`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`id`](../../Annotations/classes/WidgetAnnotation.md#id)
***
### interactive
> `get` **interactive**(): `boolean`
**`Experimental`**
Specifies whether the annotation allows user interaction.
> `set` **interactive**(`interactive`): `void`
**`Experimental`**
#### Parameters
• **interactive**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`interactive`](../../Annotations/classes/WidgetAnnotation.md#interactive)
***
### isAdded
> `get` **isAdded**(): `boolean`
**`Experimental`**
Indicates whether the annotation was added to a page
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isAdded`](../../Annotations/classes/WidgetAnnotation.md#isadded)
***
### isMaintainingAspectRatio
> `get` **isMaintainingAspectRatio**(): `boolean`
**`Experimental`**
Indicates if the annotation is maintaining its aspect ratio
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isMaintainingAspectRatio`](../../Annotations/classes/WidgetAnnotation.md#ismaintainingaspectratio)
***
### isMarkupAnnotation
> `get` **isMarkupAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a markup annotation
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isMarkupAnnotation`](../../Annotations/classes/WidgetAnnotation.md#ismarkupannotation)
***
### isModified
> `get` **isModified**(): `boolean`
**`Experimental`**
Indicates if the annotation has changes that have not yet been saved to
the document
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isModified`](../../Annotations/classes/WidgetAnnotation.md#ismodified)
***
### isMoveable
> `get` **isMoveable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be moved by the user
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isMoveable`](../../Annotations/classes/WidgetAnnotation.md#ismoveable)
***
### isResizable
> `get` **isResizable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be resized by the user
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isResizable`](../../Annotations/classes/WidgetAnnotation.md#isresizable)
***
### isRotatable
> `get` **isRotatable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be rotated by the user
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isRotatable`](../../Annotations/classes/WidgetAnnotation.md#isrotatable)
***
### isSelectable
> `get` **isSelectable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be selected by the user
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isSelectable`](../../Annotations/classes/WidgetAnnotation.md#isselectable)
***
### isWidgetAnnotation
> `get` **isWidgetAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a widget annotation
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isWidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md#iswidgetannotation)
***
### locked
> `get` **locked**(): [`AnnotationLockedState`](../../Annotations/enumerations/AnnotationLockedState.md)
**`Experimental`**
Represents the locked state of the annotation.
> `set` **locked**(`locked`): `void`
**`Experimental`**
#### Parameters
• **locked**: [`AnnotationLockedState`](../../Annotations/enumerations/AnnotationLockedState.md)
#### Returns
[`AnnotationLockedState`](../../Annotations/enumerations/AnnotationLockedState.md)
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`locked`](../../Annotations/classes/WidgetAnnotation.md#locked)
***
### page
> `get` **page**(): [`Page`](../../../classes/Page.md)
**`Experimental`**
Page in which the annotation is embedded.
> `set` **page**(`page`): `void`
**`Experimental`**
Set the page in which the annotation is embedded.
#### Parameters
• **page**: [`Page`](../../../classes/Page.md)
The page to set as the annotation's page.
#### Returns
[`Page`](../../../classes/Page.md)
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`page`](../../Annotations/classes/WidgetAnnotation.md#page)
***
### pageNumber
> `get` **pageNumber**(): `number`
**`Experimental`**
Number of the page in which the annotation is embedded.
#### Returns
`number`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`pageNumber`](../../Annotations/classes/WidgetAnnotation.md#pagenumber)
***
### privateData
> `get` **privateData**(): `object`
**`Experimental`**
Custom data to be stored with the annotation
> `set` **privateData**(`privateData`): `void`
**`Experimental`**
#### Parameters
• **privateData**: `object`
#### Returns
`object`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`privateData`](../../Annotations/classes/WidgetAnnotation.md#privatedata)
***
### renderProperties
> `get` **renderProperties**(): [`AnnotationRenderProperties`](../../Annotations/classes/AnnotationRenderProperties.md)
**`Experimental`**
Object which encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its visibility, interactivity, and other rendering behaviors.
> `set` **renderProperties**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: [`AnnotationRenderProperties`](../../Annotations/classes/AnnotationRenderProperties.md)
#### Returns
[`AnnotationRenderProperties`](../../Annotations/classes/AnnotationRenderProperties.md)
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`renderProperties`](../../Annotations/classes/WidgetAnnotation.md#renderproperties)
***
### source
> `get` **source**(): `void`
**`Experimental`**
Tag that identifies the source the annotation is coming from, if
the source is an input PDF or an input FDF.
Newly created annotations always return `null`.
#### Returns
`void`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`source`](../../Annotations/classes/WidgetAnnotation.md#source)
***
### type
> `get` **type**(): [`AnnotationType`](../../Annotations/enumerations/AnnotationType.md)
**`Experimental`**
The PDF annotation type
#### Default Value
`AnnotationType.Widget`
#### Returns
[`AnnotationType`](../../Annotations/enumerations/AnnotationType.md)
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`type`](../../Annotations/classes/WidgetAnnotation.md#type)
## Methods
### dispose()
> **dispose**(): `void`
**`Experimental`**
#### Returns
`void`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`dispose`](../../Annotations/classes/WidgetAnnotation.md#dispose)
---
## Class: RadioButtonWidget
**`Experimental`**
A radio button widget annotation
## Extends
- [`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md)
## Constructors
### new RadioButtonWidget()
> **new RadioButtonWidget**(`options`): [`RadioButtonWidget`](RadioButtonWidget.md)
**`Experimental`**
#### Parameters
• **options**: [`WidgetAnnotationOptions`](../../Annotations/interfaces/WidgetAnnotationOptions.md)
Options used to initialize annotation.
#### Returns
[`RadioButtonWidget`](RadioButtonWidget.md)
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`constructor`](../../Annotations/classes/WidgetAnnotation.md#constructors)
## Properties
### action
> **action**: [`Action`](../../Actions/classes/Action.md)
**`Experimental`**
The action that is performed when the widget annotation is clicked on
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`action`](../../Annotations/classes/WidgetAnnotation.md#action)
## Accessors
### \_\_annotation
> `get` **\_\_annotation**(): `Annotation`
**`Experimental`**
> `set` **\_\_annotation**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: `Annotation`
#### Returns
`Annotation`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`__annotation`](../../Annotations/classes/WidgetAnnotation.md#__annotation)
***
### boundingBox
> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
**`Experimental`**
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
> `set` **boundingBox**(`rectangle`): `void`
**`Experimental`**
#### Parameters
• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Returns
[`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`boundingBox`](../../Annotations/classes/WidgetAnnotation.md#boundingbox)
***
### content
> `get` **content**(): `string`
**`Experimental`**
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
> `set` **content**(`content`): `void`
**`Experimental`**
#### Parameters
• **content**: `string`
#### Returns
`string`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`content`](../../Annotations/classes/WidgetAnnotation.md#content)
***
### dateModified
> `get` **dateModified**(): `Date`
**`Experimental`**
The date and time when the annotation was most recently modified.
> `set` **dateModified**(`date`): `void`
**`Experimental`**
#### Parameters
• **date**: `Date`
#### Returns
`Date`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`dateModified`](../../Annotations/classes/WidgetAnnotation.md#datemodified)
***
### hasChanges
> `get` **hasChanges**(): `boolean`
**`Experimental`**
Indicates if the annotation has been changed since the document was opened
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`hasChanges`](../../Annotations/classes/WidgetAnnotation.md#haschanges)
***
### hidden
> `get` **hidden**(): `boolean`
**`Experimental`**
If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user.
> `set` **hidden**(`hidden`): `void`
**`Experimental`**
#### Parameters
• **hidden**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`hidden`](../../Annotations/classes/WidgetAnnotation.md#hidden)
***
### id
> `get` **id**(): `void`
**`Experimental`**
A unique identifier for the annotation.
#### Returns
`void`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`id`](../../Annotations/classes/WidgetAnnotation.md#id)
***
### interactive
> `get` **interactive**(): `boolean`
**`Experimental`**
Specifies whether the annotation allows user interaction.
> `set` **interactive**(`interactive`): `void`
**`Experimental`**
#### Parameters
• **interactive**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`interactive`](../../Annotations/classes/WidgetAnnotation.md#interactive)
***
### isAdded
> `get` **isAdded**(): `boolean`
**`Experimental`**
Indicates whether the annotation was added to a page
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isAdded`](../../Annotations/classes/WidgetAnnotation.md#isadded)
***
### isMaintainingAspectRatio
> `get` **isMaintainingAspectRatio**(): `boolean`
**`Experimental`**
Indicates if the annotation is maintaining its aspect ratio
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isMaintainingAspectRatio`](../../Annotations/classes/WidgetAnnotation.md#ismaintainingaspectratio)
***
### isMarkupAnnotation
> `get` **isMarkupAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a markup annotation
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isMarkupAnnotation`](../../Annotations/classes/WidgetAnnotation.md#ismarkupannotation)
***
### isModified
> `get` **isModified**(): `boolean`
**`Experimental`**
Indicates if the annotation has changes that have not yet been saved to
the document
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isModified`](../../Annotations/classes/WidgetAnnotation.md#ismodified)
***
### isMoveable
> `get` **isMoveable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be moved by the user
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isMoveable`](../../Annotations/classes/WidgetAnnotation.md#ismoveable)
***
### isResizable
> `get` **isResizable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be resized by the user
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isResizable`](../../Annotations/classes/WidgetAnnotation.md#isresizable)
***
### isRotatable
> `get` **isRotatable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be rotated by the user
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isRotatable`](../../Annotations/classes/WidgetAnnotation.md#isrotatable)
***
### isSelectable
> `get` **isSelectable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be selected by the user
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isSelectable`](../../Annotations/classes/WidgetAnnotation.md#isselectable)
***
### isWidgetAnnotation
> `get` **isWidgetAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a widget annotation
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isWidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md#iswidgetannotation)
***
### locked
> `get` **locked**(): [`AnnotationLockedState`](../../Annotations/enumerations/AnnotationLockedState.md)
**`Experimental`**
Represents the locked state of the annotation.
> `set` **locked**(`locked`): `void`
**`Experimental`**
#### Parameters
• **locked**: [`AnnotationLockedState`](../../Annotations/enumerations/AnnotationLockedState.md)
#### Returns
[`AnnotationLockedState`](../../Annotations/enumerations/AnnotationLockedState.md)
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`locked`](../../Annotations/classes/WidgetAnnotation.md#locked)
***
### page
> `get` **page**(): [`Page`](../../../classes/Page.md)
**`Experimental`**
Page in which the annotation is embedded.
> `set` **page**(`page`): `void`
**`Experimental`**
Set the page in which the annotation is embedded.
#### Parameters
• **page**: [`Page`](../../../classes/Page.md)
The page to set as the annotation's page.
#### Returns
[`Page`](../../../classes/Page.md)
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`page`](../../Annotations/classes/WidgetAnnotation.md#page)
***
### pageNumber
> `get` **pageNumber**(): `number`
**`Experimental`**
Number of the page in which the annotation is embedded.
#### Returns
`number`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`pageNumber`](../../Annotations/classes/WidgetAnnotation.md#pagenumber)
***
### privateData
> `get` **privateData**(): `object`
**`Experimental`**
Custom data to be stored with the annotation
> `set` **privateData**(`privateData`): `void`
**`Experimental`**
#### Parameters
• **privateData**: `object`
#### Returns
`object`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`privateData`](../../Annotations/classes/WidgetAnnotation.md#privatedata)
***
### renderProperties
> `get` **renderProperties**(): [`AnnotationRenderProperties`](../../Annotations/classes/AnnotationRenderProperties.md)
**`Experimental`**
Object which encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its visibility, interactivity, and other rendering behaviors.
> `set` **renderProperties**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: [`AnnotationRenderProperties`](../../Annotations/classes/AnnotationRenderProperties.md)
#### Returns
[`AnnotationRenderProperties`](../../Annotations/classes/AnnotationRenderProperties.md)
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`renderProperties`](../../Annotations/classes/WidgetAnnotation.md#renderproperties)
***
### source
> `get` **source**(): `void`
**`Experimental`**
Tag that identifies the source the annotation is coming from, if
the source is an input PDF or an input FDF.
Newly created annotations always return `null`.
#### Returns
`void`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`source`](../../Annotations/classes/WidgetAnnotation.md#source)
***
### type
> `get` **type**(): [`AnnotationType`](../../Annotations/enumerations/AnnotationType.md)
**`Experimental`**
The PDF annotation type
#### Default Value
`AnnotationType.Widget`
#### Returns
[`AnnotationType`](../../Annotations/enumerations/AnnotationType.md)
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`type`](../../Annotations/classes/WidgetAnnotation.md#type)
## Methods
### dispose()
> **dispose**(): `void`
**`Experimental`**
#### Returns
`void`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`dispose`](../../Annotations/classes/WidgetAnnotation.md#dispose)
---
## Class: TextBoxWidget
**`Experimental`**
A text box widget annotation
## Extends
- [`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md)
## Constructors
### new TextBoxWidget()
> **new TextBoxWidget**(`options`): [`TextBoxWidget`](TextBoxWidget.md)
**`Experimental`**
#### Parameters
• **options**: [`WidgetAnnotationOptions`](../../Annotations/interfaces/WidgetAnnotationOptions.md)
Options used to initialize annotation.
#### Returns
[`TextBoxWidget`](TextBoxWidget.md)
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`constructor`](../../Annotations/classes/WidgetAnnotation.md#constructors)
## Properties
### action
> **action**: [`Action`](../../Actions/classes/Action.md)
**`Experimental`**
The action that is performed when the widget annotation is clicked on
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`action`](../../Annotations/classes/WidgetAnnotation.md#action)
## Accessors
### \_\_annotation
> `get` **\_\_annotation**(): `Annotation`
**`Experimental`**
> `set` **\_\_annotation**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: `Annotation`
#### Returns
`Annotation`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`__annotation`](../../Annotations/classes/WidgetAnnotation.md#__annotation)
***
### boundingBox
> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
**`Experimental`**
Represents the bounding box of the annotation, which defines its position and size on the page.
The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates.
> `set` **boundingBox**(`rectangle`): `void`
**`Experimental`**
#### Parameters
• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Returns
[`Rectangle`](../../Geometry/classes/Rectangle.md)\<`PdfPoint`\>
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`boundingBox`](../../Annotations/classes/WidgetAnnotation.md#boundingbox)
***
### content
> `get` **content**(): `string`
**`Experimental`**
Text that shall be displayed for the annotation or, if this type of
annotation does not display text, an alternative description of the
annotation’s contents in human-readable form.
> `set` **content**(`content`): `void`
**`Experimental`**
#### Parameters
• **content**: `string`
#### Returns
`string`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`content`](../../Annotations/classes/WidgetAnnotation.md#content)
***
### dateModified
> `get` **dateModified**(): `Date`
**`Experimental`**
The date and time when the annotation was most recently modified.
> `set` **dateModified**(`date`): `void`
**`Experimental`**
#### Parameters
• **date**: `Date`
#### Returns
`Date`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`dateModified`](../../Annotations/classes/WidgetAnnotation.md#datemodified)
***
### hasChanges
> `get` **hasChanges**(): `boolean`
**`Experimental`**
Indicates if the annotation has been changed since the document was opened
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`hasChanges`](../../Annotations/classes/WidgetAnnotation.md#haschanges)
***
### hidden
> `get` **hidden**(): `boolean`
**`Experimental`**
If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user.
> `set` **hidden**(`hidden`): `void`
**`Experimental`**
#### Parameters
• **hidden**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`hidden`](../../Annotations/classes/WidgetAnnotation.md#hidden)
***
### id
> `get` **id**(): `void`
**`Experimental`**
A unique identifier for the annotation.
#### Returns
`void`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`id`](../../Annotations/classes/WidgetAnnotation.md#id)
***
### interactive
> `get` **interactive**(): `boolean`
**`Experimental`**
Specifies whether the annotation allows user interaction.
> `set` **interactive**(`interactive`): `void`
**`Experimental`**
#### Parameters
• **interactive**: `boolean`
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`interactive`](../../Annotations/classes/WidgetAnnotation.md#interactive)
***
### isAdded
> `get` **isAdded**(): `boolean`
**`Experimental`**
Indicates whether the annotation was added to a page
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isAdded`](../../Annotations/classes/WidgetAnnotation.md#isadded)
***
### isMaintainingAspectRatio
> `get` **isMaintainingAspectRatio**(): `boolean`
**`Experimental`**
Indicates if the annotation is maintaining its aspect ratio
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isMaintainingAspectRatio`](../../Annotations/classes/WidgetAnnotation.md#ismaintainingaspectratio)
***
### isMarkupAnnotation
> `get` **isMarkupAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a markup annotation
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isMarkupAnnotation`](../../Annotations/classes/WidgetAnnotation.md#ismarkupannotation)
***
### isModified
> `get` **isModified**(): `boolean`
**`Experimental`**
Indicates if the annotation has changes that have not yet been saved to
the document
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isModified`](../../Annotations/classes/WidgetAnnotation.md#ismodified)
***
### isMoveable
> `get` **isMoveable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be moved by the user
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isMoveable`](../../Annotations/classes/WidgetAnnotation.md#ismoveable)
***
### isResizable
> `get` **isResizable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be resized by the user
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isResizable`](../../Annotations/classes/WidgetAnnotation.md#isresizable)
***
### isRotatable
> `get` **isRotatable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be rotated by the user
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isRotatable`](../../Annotations/classes/WidgetAnnotation.md#isrotatable)
***
### isSelectable
> `get` **isSelectable**(): `boolean`
**`Experimental`**
Indicates if the annotation can be selected by the user
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isSelectable`](../../Annotations/classes/WidgetAnnotation.md#isselectable)
***
### isWidgetAnnotation
> `get` **isWidgetAnnotation**(): `boolean`
**`Experimental`**
Indicates if the annotation is a widget annotation
#### Returns
`boolean`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isWidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md#iswidgetannotation)
***
### locked
> `get` **locked**(): [`AnnotationLockedState`](../../Annotations/enumerations/AnnotationLockedState.md)
**`Experimental`**
Represents the locked state of the annotation.
> `set` **locked**(`locked`): `void`
**`Experimental`**
#### Parameters
• **locked**: [`AnnotationLockedState`](../../Annotations/enumerations/AnnotationLockedState.md)
#### Returns
[`AnnotationLockedState`](../../Annotations/enumerations/AnnotationLockedState.md)
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`locked`](../../Annotations/classes/WidgetAnnotation.md#locked)
***
### page
> `get` **page**(): [`Page`](../../../classes/Page.md)
**`Experimental`**
Page in which the annotation is embedded.
> `set` **page**(`page`): `void`
**`Experimental`**
Set the page in which the annotation is embedded.
#### Parameters
• **page**: [`Page`](../../../classes/Page.md)
The page to set as the annotation's page.
#### Returns
[`Page`](../../../classes/Page.md)
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`page`](../../Annotations/classes/WidgetAnnotation.md#page)
***
### pageNumber
> `get` **pageNumber**(): `number`
**`Experimental`**
Number of the page in which the annotation is embedded.
#### Returns
`number`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`pageNumber`](../../Annotations/classes/WidgetAnnotation.md#pagenumber)
***
### privateData
> `get` **privateData**(): `object`
**`Experimental`**
Custom data to be stored with the annotation
> `set` **privateData**(`privateData`): `void`
**`Experimental`**
#### Parameters
• **privateData**: `object`
#### Returns
`object`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`privateData`](../../Annotations/classes/WidgetAnnotation.md#privatedata)
***
### renderProperties
> `get` **renderProperties**(): [`AnnotationRenderProperties`](../../Annotations/classes/AnnotationRenderProperties.md)
**`Experimental`**
Object which encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its visibility, interactivity, and other rendering behaviors.
> `set` **renderProperties**(`v`): `void`
**`Experimental`**
#### Parameters
• **v**: [`AnnotationRenderProperties`](../../Annotations/classes/AnnotationRenderProperties.md)
#### Returns
[`AnnotationRenderProperties`](../../Annotations/classes/AnnotationRenderProperties.md)
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`renderProperties`](../../Annotations/classes/WidgetAnnotation.md#renderproperties)
***
### source
> `get` **source**(): `void`
**`Experimental`**
Tag that identifies the source the annotation is coming from, if
the source is an input PDF or an input FDF.
Newly created annotations always return `null`.
#### Returns
`void`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`source`](../../Annotations/classes/WidgetAnnotation.md#source)
***
### type
> `get` **type**(): [`AnnotationType`](../../Annotations/enumerations/AnnotationType.md)
**`Experimental`**
The PDF annotation type
#### Default Value
`AnnotationType.Widget`
#### Returns
[`AnnotationType`](../../Annotations/enumerations/AnnotationType.md)
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`type`](../../Annotations/classes/WidgetAnnotation.md#type)
## Methods
### dispose()
> **dispose**(): `void`
**`Experimental`**
#### Returns
`void`
#### Inherited from
[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`dispose`](../../Annotations/classes/WidgetAnnotation.md#dispose)
---
## Forms
## Index
### Classes
- [ButtonWidget](classes/ButtonWidget.md)
- [CheckBoxWidget](classes/CheckBoxWidget.md)
- [ComboBoxWidget](classes/ComboBoxWidget.md)
- [FormWidget](classes/FormWidget.md)
- [ListBoxWidget](classes/ListBoxWidget.md)
- [RadioButtonWidget](classes/RadioButtonWidget.md)
- [TextBoxWidget](classes/TextBoxWidget.md)
---
## Class: Inset
Inset in PDF Document
## Constructors
### new Inset()
> **new Inset**(`top`, `right`, `buttom`, `left`): [`Inset`](Inset.md)
#### Parameters
• **top**: `number`
• **right**: `number`
• **buttom**: `number`
• **left**: `number`
#### Returns
[`Inset`](Inset.md)
## Properties
### bottom
> **bottom**: `number`
***
### left
> **left**: `number`
***
### right
> **right**: `number`
***
### top
> **top**: `number`
---
## Class: Point
Represents a point in a two-dimensional coordinate system.
## Implements
- [`Cloneable`](../../../../Core/interfaces/Cloneable.md)\<[`Point`](Point.md)\>
## Constructors
### new Point()
> **new Point**(`x`, `y`): [`Point`](Point.md)
Creates a new `Point` instance with the specified coordinates.
#### Parameters
• **x**: `number` = `0`
The X value (horizontal coordinate).
• **y**: `number` = `0`
The Y value (vertical coordinate).
#### Returns
[`Point`](Point.md)
## Properties
### x
> **x**: `number`
The X value (horizontal coordinate).
***
### y
> **y**: `number`
The Y value (vertical coordinate).
## Methods
### clone()
> **clone**(): [`Point`](Point.md)
Creates a deep copy of the object.
#### Returns
[`Point`](Point.md)
A new instance that is a deep copy of the original object.
#### Implementation of
[`Cloneable`](../../../../Core/interfaces/Cloneable.md).[`clone`](../../../../Core/interfaces/Cloneable.md#clone)
***
### calculateCentroid()
> `static` **calculateCentroid**(`points`): [`Point`](Point.md)
#### Parameters
• **points**: [`Point`](Point.md)[]
#### Returns
[`Point`](Point.md)
***
### calculateNormalLineYIntercept()
> `static` **calculateNormalLineYIntercept**(`point`, `normalSlope`): `number`
#### Parameters
• **point**: [`Point`](Point.md)
• **normalSlope**: `number`
#### Returns
`number`
***
### calculatePerpendicularIntersection()
> `static` **calculatePerpendicularIntersection**(`p1`, `p2`, `p3`): [`Point`](Point.md)
#### Parameters
• **p1**: [`Point`](Point.md)
• **p2**: [`Point`](Point.md)
• **p3**: [`Point`](Point.md)
#### Returns
[`Point`](Point.md)
***
### calculateSlope()
> `static` **calculateSlope**(`p1`, `p2`): `number`
#### Parameters
• **p1**: [`Point`](Point.md)
• **p2**: [`Point`](Point.md)
#### Returns
`number`
***
### calculateYIntercept()
> `static` **calculateYIntercept**(`point`, `slope`): `number`
#### Parameters
• **point**: [`Point`](Point.md)
• **slope**: `number`
#### Returns
`number`
***
### findIntersection()
> `static` **findIntersection**(`slope1`, `yIntercept1`, `slope2`, `yIntercept2`): [`Point`](Point.md)
#### Parameters
• **slope1**: `number`
• **yIntercept1**: `number`
• **slope2**: `number`
• **yIntercept2**: `number`
#### Returns
[`Point`](Point.md)
---
## Class: Quadrilateral\
Represents a polygon with four sides and four corners.
## Type Parameters
• **T** *extends* [`Point`](Point.md)
## Implements
- [`Cloneable`](../../../../Core/interfaces/Cloneable.md)\<[`Quadrilateral`](Quadrilateral.md)\<`T`\>\>
## Constructors
### new Quadrilateral()
> **new Quadrilateral**\<`T`\>(`p1`, `p2`, `p3`, `p4`): [`Quadrilateral`](Quadrilateral.md)\<`T`\>
Creates a new `Quadrilateral` instance with the specified corner coordinates.
Accepts `Point` instances for each corner.
#### Parameters
• **p1**: `T`
The Point representing the first corner.
• **p2**: `T`
The Point representing the second corner.
• **p3**: `T`
The Point representing the third corner.
• **p4**: `T`
The Point representing the fourth corner.
#### Returns
[`Quadrilateral`](Quadrilateral.md)\<`T`\>
### new Quadrilateral()
> **new Quadrilateral**\<`T`\>(`x1`, `y1`, `x2`, `y2`, `x3`, `y3`, `x4`, `y4`): [`Quadrilateral`](Quadrilateral.md)\<`T`\>
Creates a new `Quadrilateral` instance with the specified corner coordinates.
#### Parameters
• **x1**: `number`
The X coordinate of the first corner.
• **y1**: `number`
The Y coordinate of the first corner.
• **x2**: `number`
The X coordinate of the second corner.
• **y2**: `number`
The Y coordinate of the second corner.
• **x3**: `number`
The X coordinate of the third corner.
• **y3**: `number`
The Y coordinate of the third corner.
• **x4**: `number`
The X coordinate of the fourth corner.
• **y4**: `number`
The Y coordinate of the fourth corner.
#### Returns
[`Quadrilateral`](Quadrilateral.md)\<`T`\>
## Properties
### p1
> **p1**: `T`
The `Point` representing the first corner.
***
### p2
> **p2**: `T`
The `Point` representing the second corner.
***
### p3
> **p3**: `T`
The `Point` representing the third corner.
***
### p4
> **p4**: `T`
The `Point` representing the fourth corner.
## Accessors
### points
> `get` **points**(): `T`[]
#### Returns
`T`[]
## Methods
### clone()
> **clone**(): [`Quadrilateral`](Quadrilateral.md)\<`T`\>
Creates a deep copy of the object.
#### Returns
[`Quadrilateral`](Quadrilateral.md)\<`T`\>
A new instance that is a deep copy of the original object.
#### Implementation of
[`Cloneable`](../../../../Core/interfaces/Cloneable.md).[`clone`](../../../../Core/interfaces/Cloneable.md#clone)
***
### containsPoint()
> **containsPoint**(`p`): `boolean`
Checks if a given point is inside the quadrilateral.
#### Parameters
• **p**: `T`
The point to check, which is of type `T` extending `Point`.
#### Returns
`boolean`
`true` if the point is inside the quadrilateral, otherwise `false`.
---
## Class: Rectangle\
Represents a rectangle in a two-dimensional coordinate system.
## Type Parameters
• **T** *extends* [`Point`](Point.md)
## Implements
- [`Cloneable`](../../../../Core/interfaces/Cloneable.md)\<[`Rectangle`](Rectangle.md)\<`T`\>\>
## Constructors
### new Rectangle()
> **new Rectangle**\<`T`\>(`topLeft`, `size`): [`Rectangle`](Rectangle.md)\<`T`\>
Creates a new `Rectangle` instance with the specified top-left corner and size.
#### Parameters
• **topLeft**: `T`
The top-left corner of the rectangle.
• **size**: [`Size`](Size.md)
The size of the rectangle.
#### Returns
[`Rectangle`](Rectangle.md)\<`T`\>
### new Rectangle()
> **new Rectangle**\<`T`\>(`x`, `y`, `width`, `height`): [`Rectangle`](Rectangle.md)\<`T`\>
Creates a new `Rectangle` instance with the specified coordinates and dimensions.
#### Parameters
• **x**: `number`
The X coordinate of the top-left corner.
• **y**: `number`
The Y coordinate of the top-left corner.
• **width**: `number`
The width of the rectangle.
• **height**: `number`
The height of the rectangle.
#### Returns
[`Rectangle`](Rectangle.md)\<`T`\>
## Properties
### size
> **size**: [`Size`](Size.md)
The size of the rectangle.
***
### topLeft
> **topLeft**: `T`
The top-left corner of the rectangle.
## Accessors
### height
> `get` **height**(): `number`
The height of the rectangle.
> `set` **height**(`height`): `void`
#### Parameters
• **height**: `number`
#### Returns
`number`
***
### width
> `get` **width**(): `number`
The width of the rectangle.
> `set` **width**(`width`): `void`
#### Parameters
• **width**: `number`
#### Returns
`number`
## Methods
### clone()
> **clone**(): [`Rectangle`](Rectangle.md)\<`T`\>
Creates a deep copy of the object.
#### Returns
[`Rectangle`](Rectangle.md)\<`T`\>
A new instance that is a deep copy of the original object.
#### Implementation of
[`Cloneable`](../../../../Core/interfaces/Cloneable.md).[`clone`](../../../../Core/interfaces/Cloneable.md#clone)
***
### calculateBoundingBox()
> `static` **calculateBoundingBox**(`points`): [`Rectangle`](Rectangle.md)\<[`Point`](Point.md)\>
Calculates the bounding box that encompasses a given set of points.
#### Parameters
• **points**: [`Point`](Point.md)[]
An array of [Point](Point.md) objects representing the points to enclose.
#### Returns
[`Rectangle`](Rectangle.md)\<[`Point`](Point.md)\>
A [Rectangle](Rectangle.md) representing the bounding box of the points,
or `null` if the input array is empty.
#### Remarks
This method determines the smallest rectangular area that fully contains
all the provided points. It iterates through the points to find the minimum
and maximum x and y coordinates, then constructs a [Rectangle](Rectangle.md) using
those boundaries.
If the input array is empty, the function returns `null`.
---
## Class: Size
Represents the dimensions of an object in terms of width and height.
## Implements
- [`Cloneable`](../../../../Core/interfaces/Cloneable.md)\<[`Size`](Size.md)\>
## Constructors
### new Size()
> **new Size**(`width`, `height`): [`Size`](Size.md)
Creates a new Size instance with the specified width and height.
#### Parameters
• **width**: `number` = `0`
The width of the object.
• **height**: `number` = `0`
The height of the object.
#### Returns
[`Size`](Size.md)
## Properties
### height
> **height**: `number`
The height of the object.
***
### width
> **width**: `number`
The width of the object.
## Methods
### clone()
> **clone**(): [`Size`](Size.md)
Creates a deep copy of the object.
#### Returns
[`Size`](Size.md)
A new instance that is a deep copy of the original object.
#### Implementation of
[`Cloneable`](../../../../Core/interfaces/Cloneable.md).[`clone`](../../../../Core/interfaces/Cloneable.md#clone)
---
## Enumeration: Orientation
## Enumeration Members
### landscape
> **landscape**: `0`
landscape orientation (width > height)
***
### portrait
> **portrait**: `1`
portrait orientation (height > width)
***
### square
> **square**: `2`
square orientation (height == width)
---
## Geometry
## Index
### Enumerations
- [Orientation](enumerations/Orientation.md)
### Classes
- [Inset](classes/Inset.md)
- [Point](classes/Point.md)
- [Quadrilateral](classes/Quadrilateral.md)
- [Rectangle](classes/Rectangle.md)
- [Size](classes/Size.md)
### Variables
- [PaperSize](variables/PaperSize.md)
---
## Variable: PaperSize
> `const` **PaperSize**: `object`
predefined paper sizes
## Type declaration
### a4\_landscape
> **a4\_landscape**: `object`
### a4\_landscape.format
> **format**: `string` = `'A4'`
### a4\_landscape.height
> **height**: `number` = `123`
### a4\_landscape.orientation
> **orientation**: [`Orientation`](../enumerations/Orientation.md) = `Orientation.landscape`
### a4\_landscape.width
> **width**: `number` = `123`
### a4\_portait
> **a4\_portait**: `object`
### a4\_portait.format
> **format**: `string` = `'A4'`
### a4\_portait.height
> **height**: `number` = `123`
### a4\_portait.orientation
> **orientation**: [`Orientation`](../enumerations/Orientation.md) = `Orientation.portrait`
### a4\_portait.width
> **width**: `number` = `123`
---
## Class: DocumentTextSearchService
Service for searching text within a document.
Inherits functionality from the generic SearchService class, specifying parameters for text search and returning an array of DocumentTextSearchResult objects.
## Extends
- [`SearchService`](SearchService.md)\<[`DocumentTextSearchParams`](../interfaces/DocumentTextSearchParams.md), [`DocumentTextSearchResult`](../interfaces/DocumentTextSearchResult.md)[]\>
## Constructors
### new DocumentTextSearchService()
> **new DocumentTextSearchService**(`strategy`): [`DocumentTextSearchService`](DocumentTextSearchService.md)
Constructs a new SearchService instance with the specified search strategy.
#### Parameters
• **strategy**: [`SearchStrategy`](SearchStrategy.md)\<[`DocumentTextSearchParams`](../interfaces/DocumentTextSearchParams.md), [`DocumentTextSearchResult`](../interfaces/DocumentTextSearchResult.md)[]\>
The search strategy to be used for executing search operations.
#### Returns
[`DocumentTextSearchService`](DocumentTextSearchService.md)
#### Inherited from
[`SearchService`](SearchService.md).[`constructor`](SearchService.md#constructors)
## Properties
### strategy
> **strategy**: [`SearchStrategy`](SearchStrategy.md)\<[`DocumentTextSearchParams`](../interfaces/DocumentTextSearchParams.md), [`DocumentTextSearchResult`](../interfaces/DocumentTextSearchResult.md)[]\>
The search strategy associated with this search service.
#### Inherited from
[`SearchService`](SearchService.md).[`strategy`](SearchService.md#strategy)
## Methods
### execute()
> **execute**(`params`): [`SearchExecution`](SearchExecution.md)\<[`DocumentTextSearchResult`](../interfaces/DocumentTextSearchResult.md)[]\>
Executes a search operation using the specified parameters.
#### Parameters
• **params**: [`DocumentTextSearchParams`](../interfaces/DocumentTextSearchParams.md)
The parameters for the search operation.
#### Returns
[`SearchExecution`](SearchExecution.md)\<[`DocumentTextSearchResult`](../interfaces/DocumentTextSearchResult.md)[]\>
A SearchExecution object representing the ongoing search operation.
#### Inherited from
[`SearchService`](SearchService.md).[`execute`](SearchService.md#execute)
---
## Class: DocumentTextSearchStrategy
Represents a search strategy specifically designed for searching text within a document.
Inherits functionality from the generic `SearchStrategy` class, specifying `DocumentTextSearchParams` and returning an array of `DocumentTextSearchResult` objects.
## Extends
- [`SearchStrategy`](SearchStrategy.md)\<[`DocumentTextSearchParams`](../interfaces/DocumentTextSearchParams.md), [`DocumentTextSearchResult`](../interfaces/DocumentTextSearchResult.md)[]\>
## Constructors
### new DocumentTextSearchStrategy()
> **new DocumentTextSearchStrategy**(`document`): [`DocumentTextSearchStrategy`](DocumentTextSearchStrategy.md)
Constructs a new `DocumentTextSearchStrategy` instance.
#### Parameters
• **document**: [`Document`](../../../classes/Document.md)
Parameter representing the PDF document to be searched.
#### Returns
[`DocumentTextSearchStrategy`](DocumentTextSearchStrategy.md)
#### Overrides
[`SearchStrategy`](SearchStrategy.md).[`constructor`](SearchStrategy.md#constructors)
## Properties
### document
> **document**: [`Document`](../../../classes/Document.md)
The `Pdf.Document` instance associated with this search strategy.
#### Inherited from
[`SearchStrategy`](SearchStrategy.md).[`document`](SearchStrategy.md#document)
## Methods
### execute()
> **execute**(`params`): [`SearchExecution`](SearchExecution.md)\<[`DocumentTextSearchResult`](../interfaces/DocumentTextSearchResult.md)[]\>
Executes the search strategy asynchronously.
#### Parameters
• **params**: [`DocumentTextSearchParams`](../interfaces/DocumentTextSearchParams.md)
The parameters for the search operation.
#### Returns
[`SearchExecution`](SearchExecution.md)\<[`DocumentTextSearchResult`](../interfaces/DocumentTextSearchResult.md)[]\>
A `SearchExecution` object representing the ongoing search operation.
#### Inherited from
[`SearchStrategy`](SearchStrategy.md).[`execute`](SearchStrategy.md#execute)
---
## Class: SearchExecution\
Event emitter for search execution events.
Extends the EventEmitter class to handle events related to search execution.
## Extends
- [`EventEmitter`](../../../../Core/classes/EventEmitter.md)\<[`SearchExecutionEventMap`](../interfaces/SearchExecutionEventMap.md)\<`T`\>\>
## Type Parameters
• **T**
## Implements
- [`SearchExecution`](SearchExecution.md)\<`T`\>
## Constructors
### new SearchExecution()
> **new SearchExecution**\<`T`\>(): [`SearchExecution`](SearchExecution.md)\<`T`\>
Constructs a new `SearchExecution` instance.
Initializes the search execution with a Promise to track the search result.
#### Returns
[`SearchExecution`](SearchExecution.md)\<`T`\>
#### Overrides
`EventEmitter>.constructor`
## Properties
### result
> **result**: `Promise`\<`T`\>
A Promise representing the result of the search execution.
#### Implementation of
`SearchExecution.result`
***
### state
> **state**: [`SearchExecutionState`](../enumerations/SearchExecutionState.md) = `SearchExecutionState.Executing`
The current state of the search execution.
#### Implementation of
`SearchExecution.state`
## Methods
### addEventListener()
> **addEventListener**\<`K`\>(`type`, `listener`): `void`
Register a function that will be called whenever the specified event is delivered.
#### Type Parameters
• **K** *extends* keyof [`SearchExecutionEventMap`](../interfaces/SearchExecutionEventMap.md)\<`T`\>
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event type to listen for.
• **listener**
The function that will be executed when an event of the specified type occurs.
#### Returns
`void`
#### Implementation of
`SearchExecution.addEventListener`
#### Inherited from
`EventEmitter.addEventListener`
***
### cancel()
> **cancel**(): `void`
Cancels the search execution.
Sets the search execution state to "canceled" and dispatches a searchCanceled event.
#### Returns
`void`
#### Implementation of
`SearchExecution.cancel`
***
### dispatchEvent()
> **dispatchEvent**\<`K`\>(`type`, `args`): `void`
Dispatches an event to all registered listeners.
#### Type Parameters
• **K** *extends* keyof [`SearchExecutionEventMap`](../interfaces/SearchExecutionEventMap.md)\<`T`\>
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event type to dispatch.
• **args**: `Parameters`\<[`SearchExecutionEventMap`](../interfaces/SearchExecutionEventMap.md)\<`T`\>\[`K`\]\>
The data associated with the event.
#### Returns
`void`
#### Implementation of
`SearchExecution.dispatchEvent`
#### Inherited from
`EventEmitter.dispatchEvent`
***
### onErrorOccurred()
> **onErrorOccurred**(`error`): `void`
Handles errors that occur during the search execution.
Rejects the search Promise with the error and dispatches an errorOccurred event.
#### Parameters
• **error**: `Error`
The error that occurred during the search execution.
#### Returns
`void`
#### Implementation of
`SearchExecution.onErrorOccurred`
***
### onSearchFinished()
> **onSearchFinished**(`result`): `void`
Handles the completion of the search execution.
Sets the search execution state to "finished", resolves the search Promise with the result, and dispatches a searchFinished event.
#### Parameters
• **result**: `T`
The result of the search execution.
#### Returns
`void`
#### Implementation of
`SearchExecution.onSearchFinished`
***
### onSearchResultsFound()
> **onSearchResultsFound**(`result`): `void`
Handles the discovery of search results.
Dispatches a searchResultsFound event.
#### Parameters
• **result**: `T`
The result of the search execution.
#### Returns
`void`
#### Implementation of
`SearchExecution.onSearchResultsFound`
***
### onSearchStarted()
> **onSearchStarted**(`result`): `void`
Handles the start of the search execution.
Sets the search execution state to "executing" and dispatches a searchStarted event.
#### Parameters
• **result**: `T`
The result of the search execution.
#### Returns
`void`
#### Implementation of
`SearchExecution.onSearchStarted`
***
### removeAllListeners()
> **removeAllListeners**\<`K`\>(`type`): `void`
Remove all listeners for a given event.
#### Type Parameters
• **K** *extends* keyof [`SearchExecutionEventMap`](../interfaces/SearchExecutionEventMap.md)\<`T`\>
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event for which to remove all listeners.
#### Returns
`void`
#### Implementation of
`SearchExecution.removeAllListeners`
#### Inherited from
`EventEmitter.removeAllListeners`
***
### removeEventListener()
> **removeEventListener**\<`K`\>(`type`, `listener`): `void`
Removes an event listener previously registered with addEventListener.
#### Type Parameters
• **K** *extends* keyof [`SearchExecutionEventMap`](../interfaces/SearchExecutionEventMap.md)\<`T`\>
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event for which to remove an event listener.
• **listener**
The event listener function of the event handler to remove from the event target.
#### Returns
`void`
#### Implementation of
`SearchExecution.removeEventListener`
#### Inherited from
`EventEmitter.removeEventListener`
---
## Class: SearchService\
Represents a search service that facilitates executing search operations using a specified search strategy.
## Extended by
- [`DocumentTextSearchService`](DocumentTextSearchService.md)
## Type Parameters
• **T**
The type of parameters used for the search operation.
• **K**
The type of result returned by the search operation.
## Constructors
### new SearchService()
> **new SearchService**\<`T`, `K`\>(`strategy`): [`SearchService`](SearchService.md)\<`T`, `K`\>
Constructs a new SearchService instance with the specified search strategy.
#### Parameters
• **strategy**: [`SearchStrategy`](SearchStrategy.md)\<`T`, `K`\>
The search strategy to be used for executing search operations.
#### Returns
[`SearchService`](SearchService.md)\<`T`, `K`\>
## Properties
### strategy
> **strategy**: [`SearchStrategy`](SearchStrategy.md)\<`T`, `K`\>
The search strategy associated with this search service.
## Methods
### execute()
> **execute**(`params`): [`SearchExecution`](SearchExecution.md)\<`K`\>
Executes a search operation using the specified parameters.
#### Parameters
• **params**: `T`
The parameters for the search operation.
#### Returns
[`SearchExecution`](SearchExecution.md)\<`K`\>
A SearchExecution object representing the ongoing search operation.
---
## Class: `abstract` SearchStrategy\
Represents an abstract search strategy template for executing search operations.
## Extended by
- [`DocumentTextSearchStrategy`](DocumentTextSearchStrategy.md)
## Type Parameters
• **T**
The type of parameters used for the search operation.
• **K**
The type of result returned by the search operation.
## Constructors
### new SearchStrategy()
> **new SearchStrategy**\<`T`, `K`\>(): [`SearchStrategy`](SearchStrategy.md)\<`T`, `K`\>
#### Returns
[`SearchStrategy`](SearchStrategy.md)\<`T`, `K`\>
## Properties
### document
> **document**: [`Document`](../../../classes/Document.md)
The `Pdf.Document` instance associated with this search strategy.
## Methods
### execute()
> **execute**(`params`): [`SearchExecution`](SearchExecution.md)\<`K`\>
Executes the search strategy asynchronously.
#### Parameters
• **params**: `T`
The parameters for the search operation.
#### Returns
[`SearchExecution`](SearchExecution.md)\<`K`\>
A `SearchExecution` object representing the ongoing search operation.
---
## Enumeration: SearchExecutionState
Enumerates different states of a search execution.
Represents the current state of the search operation, such as executing, finished, canceled, or error occurred.
## Enumeration Members
### Canceled
> **Canceled**: `"canceled"`
The search execution has been canceled.
***
### ErrorOccurred
> **ErrorOccurred**: `"error-occurred"`
An error occurred during the search execution.
***
### Executing
> **Executing**: `"executing"`
The search execution is currently ongoing.
***
### Finished
> **Finished**: `"finished"`
The search execution has finished successfully.
---
## Search
## Index
### Enumerations
- [SearchExecutionState](enumerations/SearchExecutionState.md)
### Classes
- [DocumentTextSearchService](classes/DocumentTextSearchService.md)
- [DocumentTextSearchStrategy](classes/DocumentTextSearchStrategy.md)
- [SearchExecution](classes/SearchExecution.md)
- [SearchService](classes/SearchService.md)
- [SearchStrategy](classes/SearchStrategy.md)
### Interfaces
- [DocumentTextSearchParams](interfaces/DocumentTextSearchParams.md)
- [DocumentTextSearchResult](interfaces/DocumentTextSearchResult.md)
- [DocumentTextSearchResultContextInfo](interfaces/DocumentTextSearchResultContextInfo.md)
- [SearchExecutionEventMap](interfaces/SearchExecutionEventMap.md)
---
## Interface: DocumentTextSearchParams
Represents the parameters for searching text within a document.
These parameters include the search query, case sensitivity, and whether to use regular expressions.
## Properties
### caseSensitive
> **caseSensitive**: `boolean`
Specifies whether the search should be case-sensitive.
***
### query
> **query**: `string`
The search query to be used.
***
### regularExpression
> **regularExpression**: `boolean`
Specifies whether the search query is a regular expression.
***
### startPageNumber
> **startPageNumber**: `number`
Starting page for the search algorithm.
---
## Interface: DocumentTextSearchResult(Interfaces)
Represents the result of a text search within a document.
Includes the matched text, context text surrounding the match, page number, and quadrilaterals outlining the position of the text on the page.
## Properties
### contextInfo
> **contextInfo**: [`DocumentTextSearchResultContextInfo`](DocumentTextSearchResultContextInfo.md)
The context info containing text that surrounds matched text.
***
### pageNumber
> **pageNumber**: `number`
The page number where the text was found.
***
### quadrilaterals
> **quadrilaterals**: [`Quadrilateral`](../../Geometry/classes/Quadrilateral.md)\<`PdfPoint`\>[]
Quadrilaterals outlining the position of the text on the page.
***
### text
> **text**: `string`
The matched text found during the search.
---
## Interface: DocumentTextSearchResultContextInfo
Represents information about context text that surrounds matched text inside the document text.
## Properties
### matchEndIndex
> **matchEndIndex**: `number`
The match end index inside the context text.
***
### matchStartIndex
> **matchStartIndex**: `number`
The match start index inside the context text.
***
### text
> **text**: `string`
The context text surrounding the matched text.
---
## Interface: SearchExecutionEventMap\
Interface defining event types for `SearchExecution`.
Specifies the types of events that can be emitted during a search execution.
## Type Parameters
• **T**
## Properties
### errorOccurred()
> **errorOccurred**: (`error`) => `void`
Event triggered when an error occurs during the search execution.
#### Parameters
• **error**: `Error`
The error that occurred during the search execution.
#### Returns
`void`
***
### searchCanceled()
> **searchCanceled**: () => `void`
Event triggered when the search execution is canceled.
#### Returns
`void`
***
### searchFinished()
> **searchFinished**: (`result`) => `void`
Event triggered when the search execution finishes.
#### Parameters
• **result**: `T`
The result of the search execution.
#### Returns
`void`
***
### searchResultsFound()
> **searchResultsFound**: (`result`) => `void`
Event triggered when search results are found.
#### Parameters
• **result**: `T`
The result of the search execution.
#### Returns
`void`
***
### searchStarted()
> **searchStarted**: (`result`) => `void`
Event triggered when the search execution starts.
#### Parameters
• **result**: `T`
The result of the search execution.
#### Returns
`void`
---
## Class: AccessibilityLayer
Represents a layer that provides accessibility features for text fragments in a PDF document.
This layer creates an invisible HTML structure that aligns with the text fragments on the page,
enabling screen readers and other accessibility tools to interact with the content.
## Extends
- [`Layer`](Layer.md)\<`HTMLDivElement`\>
## Constructors
### new AccessibilityLayer()
> **new AccessibilityLayer**(`id`, `documentViewPage`): [`AccessibilityLayer`](AccessibilityLayer.md)
Creates an instance of Layer.
#### Parameters
• **id**: `string`
The unique identifier for the layer.
• **documentViewPage**: [`DocumentViewPage`](DocumentViewPage.md)
The associated document view page.
#### Returns
[`AccessibilityLayer`](AccessibilityLayer.md)
#### Inherited from
[`Layer`](Layer.md).[`constructor`](Layer.md#constructors)
## Accessors
### documentViewPage
> `get` **documentViewPage**(): [`DocumentViewPage`](DocumentViewPage.md)
Gets the document view page associated with this layer.
#### Returns
[`DocumentViewPage`](DocumentViewPage.md)
#### Inherited from
[`Layer`](Layer.md).[`documentViewPage`](Layer.md#documentviewpage)
***
### id
> `get` **id**(): `string`
Gets the unique identifier of the layer.
#### Returns
`string`
#### Inherited from
[`Layer`](Layer.md).[`id`](Layer.md#id)
***
### nativeElement
> `get` **nativeElement**(): `T`
Gets the native HTML element of this layer.
#### Returns
`T`
#### Inherited from
[`Layer`](Layer.md).[`nativeElement`](Layer.md#nativeelement)
***
### size
> `get` **size**(): [`Size`](../../Pdf/namespaces/Geometry/classes/Size.md)
Gets the size of the layer.
> `set` **size**(`v`): `void`
Sets the size of the layer and dispatches a size change event if the size is different.
#### Parameters
• **v**: [`Size`](../../Pdf/namespaces/Geometry/classes/Size.md)
The new size to be set.
#### Returns
[`Size`](../../Pdf/namespaces/Geometry/classes/Size.md)
#### Inherited from
[`Layer`](Layer.md).[`size`](Layer.md#size)
## Methods
### addEventListener()
> **addEventListener**\<`K`\>(`type`, `listener`): `void`
Register a function that will be called whenever the specified event is delivered.
#### Type Parameters
• **K** *extends* `"sizeChanged"`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event type to listen for.
• **listener**
The function that will be executed when an event of the specified type occurs.
#### Returns
`void`
#### Inherited from
[`Layer`](Layer.md).[`addEventListener`](Layer.md#addeventlistener)
***
### dispatchEvent()
> **dispatchEvent**\<`K`\>(`type`, `args`): `void`
Dispatches an event to all registered listeners.
#### Type Parameters
• **K** *extends* `"sizeChanged"`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event type to dispatch.
• **args**: `Parameters`\<[`LayerEventMap`](../interfaces/LayerEventMap.md)\[`K`\]\>
The data associated with the event.
#### Returns
`void`
#### Inherited from
[`Layer`](Layer.md).[`dispatchEvent`](Layer.md#dispatchevent)
***
### removeAllListeners()
> **removeAllListeners**\<`K`\>(`type`): `void`
Remove all listeners for a given event.
#### Type Parameters
• **K** *extends* `"sizeChanged"`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event for which to remove all listeners.
#### Returns
`void`
#### Inherited from
[`Layer`](Layer.md).[`removeAllListeners`](Layer.md#removealllisteners)
***
### removeEventListener()
> **removeEventListener**\<`K`\>(`type`, `listener`): `void`
Removes an event listener previously registered with addEventListener.
#### Type Parameters
• **K** *extends* `"sizeChanged"`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event for which to remove an event listener.
• **listener**
The event listener function of the event handler to remove from the event target.
#### Returns
`void`
#### Inherited from
[`Layer`](Layer.md).[`removeEventListener`](Layer.md#removeeventlistener)
---
## Class: DocumentView
Class for managing the presentation and interaction with a PDF document within a container element.
## Extends
- [`EventEmitter`](../../Core/classes/EventEmitter.md)\<[`DocumentViewEventMap`](../interfaces/DocumentViewEventMap.md)\>
## Implements
- [`Disposable`](../../Core/interfaces/Disposable.md)
## Constructors
### new DocumentView()
> **new DocumentView**(`container`, `options`?): [`DocumentView`](DocumentView.md)
Constructor for the DocumentView class.
#### Parameters
• **container**: `HTMLElement`
The container element in which the document view will be displayed.
• **options?**: [`DocumentViewOptions`](../type-aliases/DocumentViewOptions.md)
#### Returns
[`DocumentView`](DocumentView.md)
#### Overrides
[`EventEmitter`](../../Core/classes/EventEmitter.md).[`constructor`](../../Core/classes/EventEmitter.md#constructors)
## Properties
### DEFAULT\_DPI
> `readonly` `static` **DEFAULT\_DPI**: `number`
## Accessors
### accessibilityLayerEnabled
> `get` **accessibilityLayerEnabled**(): `boolean`
Enables or disables the accessibility layer for the document view.
When enabled, the accessibility layer provides support for screen readers and other accessibility tools
by creating an invisible HTML structure that aligns with the text fragments on the page.
> `set` **accessibilityLayerEnabled**(`v`): `void`
#### Parameters
• **v**: `boolean`
#### Returns
`boolean`
***
### currentPageNumber
> `get` **currentPageNumber**(): `number`
Gets or sets the currently most visible page.
> `set` **currentPageNumber**(`pageNumber`): `void`
#### Parameters
• **pageNumber**: `number`
#### Returns
`number`
The number of the page which covers the largest area on the viewport, or `null` if the document view is not initialized.
If multiple pages cover the same amount of space, the one with the smaller page number is returned.
***
### dpi
> `get` **dpi**(): `number`
Gets the `dpi` (Dots Per Inch) value which influences the rendering resolution of a document view.
Higher DPI values result in higher resolution images, which can make them appear sharper and more detailed.
#### Default Value
`window.devicePixelRatio * 96`
#### Returns
`number`
***
### firstVisiblePageNumber
> `get` **firstVisiblePageNumber**(): `number`
Gets the page number of the first visible page in the document view.
#### Returns
`number`
The page number of the first visible page, or `null` if the document view is not initialized.
***
### fitMode
> `get` **fitMode**(): [`FitMode`](../../Pdf/enumerations/FitMode.md)
**`Experimental`**
Gets or sets the fit mode for the document view.
> `set` **fitMode**(`fitMode`): `void`
#### Parameters
• **fitMode**: [`FitMode`](../../Pdf/enumerations/FitMode.md)
#### Returns
[`FitMode`](../../Pdf/enumerations/FitMode.md)
***
### lastVisiblePageNumber
> `get` **lastVisiblePageNumber**(): `number`
Gets the page number of the last visible page in the document view.
#### Returns
`number`
The page number of the last visible page, or `null` if the document view is not initialized.
***
### pageLayoutMode
> `get` **pageLayoutMode**(): [`PageLayoutMode`](../../Pdf/enumerations/PageLayoutMode.md)
**`Experimental`**
Gets or sets the page layout mode for the document view.
> `set` **pageLayoutMode**(`pageLayoutMode`): `void`
#### Parameters
• **pageLayoutMode**: [`PageLayoutMode`](../../Pdf/enumerations/PageLayoutMode.md)
#### Returns
[`PageLayoutMode`](../../Pdf/enumerations/PageLayoutMode.md)
***
### pdfDocument
> `get` **pdfDocument**(): [`Document`](../../Pdf/classes/Document.md)
Gets `Pdf.Document` attached to the `DocumentView`.
#### Returns
[`Document`](../../Pdf/classes/Document.md)
***
### rotation
> `get` **rotation**(): [`Rotation`](../../Pdf/enumerations/Rotation.md)
**`Experimental`**
Gets or sets the rotation for the document view.
> `set` **rotation**(`rotation`): `void`
#### Parameters
• **rotation**: [`Rotation`](../../Pdf/enumerations/Rotation.md)
#### Returns
[`Rotation`](../../Pdf/enumerations/Rotation.md)
***
### scrollAllowance
> `get` **scrollAllowance**(): `ScrollAllowance`
Get the current scroll allowances
#### Returns
`ScrollAllowance`
***
### scrollContainer
> `get` **scrollContainer**(): `HTMLDivElement`
Retrieves the scroll container element.
The scroll container holds the individual PDF pages within the viewport.
This element manages the scrolling behavior and allows navigation through
different pages of the PDF document.
#### Returns
`HTMLDivElement`
The scroll container element.
***
### slidingWindow
> `get` **slidingWindow**(): `Map`\<`number`, [`DocumentViewPage`](DocumentViewPage.md)\>
Gets pages in sliding window.
#### Returns
`Map`\<`number`, [`DocumentViewPage`](DocumentViewPage.md)\>
***
### viewport
> `get` **viewport**(): `HTMLDivElement`
Retrieves the viewport element.
The viewport represents the entire document view of the PDF.
It acts as the main container that defines the visible area of the PDF document.
#### Returns
`HTMLDivElement`
The viewport container element.
***
### zoom
> `get` **zoom**(): `number`
Gets or sets the currently used zoom factor as a floating-point number.
1 corresponds to a zoom level of 100%.
> `set` **zoom**(`zoom`): `void`
#### Parameters
• **zoom**: `number`
#### Returns
`number`
Zoom level or null if the document view is not initialized.
***
### zoomLevels
> `get` **zoomLevels**(): `number`[]
Gets or sets the array of zoom levels available for the document view.
> `set` **zoomLevels**(`zoomLevels`): `void`
#### Parameters
• **zoomLevels**: `number`[]
#### Returns
`number`[]
## Methods
### addEventListener()
> **addEventListener**\<`K`\>(`type`, `listener`): `void`
Register a function that will be called whenever the specified event is delivered.
#### Type Parameters
• **K** *extends* keyof [`DocumentViewEventMap`](../interfaces/DocumentViewEventMap.md)
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event type to listen for.
• **listener**
The function that will be executed when an event of the specified type occurs.
#### Returns
`void`
#### Inherited from
[`EventEmitter`](../../Core/classes/EventEmitter.md).[`addEventListener`](../../Core/classes/EventEmitter.md#addeventlistener)
***
### dispatchEvent()
> **dispatchEvent**\<`K`\>(`type`, `args`): `void`
Dispatches an event to all registered listeners.
#### Type Parameters
• **K** *extends* keyof [`DocumentViewEventMap`](../interfaces/DocumentViewEventMap.md)
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event type to dispatch.
• **args**: `Parameters`\<[`DocumentViewEventMap`](../interfaces/DocumentViewEventMap.md)\[`K`\]\>
The data associated with the event.
#### Returns
`void`
#### Inherited from
[`EventEmitter`](../../Core/classes/EventEmitter.md).[`dispatchEvent`](../../Core/classes/EventEmitter.md#dispatchevent)
***
### dispose()
> **dispose**(): `void`
Disposes of the object, releasing any resources it holds.
The `dispose` method is responsible for performing cleanup operations and releasing
any resources acquired by the object. Once an object is disposed, it should not
be used, and attempts to do so may result in undefined behavior.
#### Returns
`void`
#### Implementation of
[`Disposable`](../../Core/interfaces/Disposable.md).[`dispose`](../../Core/interfaces/Disposable.md#dispose)
***
### goToDestination()
> **goToDestination**(`destination`): `void`
Navigates to the specified destination in the document view.
#### Parameters
• **destination**: [`Destination`](../../Pdf/interfaces/Destination.md)
The destination to navigate to.
#### Returns
`void`
***
### goToPage()
> **goToPage**(`pageNumber`): `any`
Navigates to the specified page in the document view.
#### Parameters
• **pageNumber**: `number`
The page number to navigate to.
#### Returns
`any`
***
### initialize()
> **initialize**(`pdfDocument`): `void`
Initializes the document view.
#### Parameters
• **pdfDocument**: [`Document`](../../Pdf/classes/Document.md)
The PDF document which will be displayed inside the document view.
#### Returns
`void`
***
### nextPage()
> **nextPage**(): `any`
Navigates to the next page in the document view.
#### Returns
`any`
***
### previousPage()
> **previousPage**(): `any`
Navigates to the previous page in the document view.
#### Returns
`any`
***
### removeAllListeners()
> **removeAllListeners**\<`K`\>(`type`): `void`
Remove all listeners for a given event.
#### Type Parameters
• **K** *extends* keyof [`DocumentViewEventMap`](../interfaces/DocumentViewEventMap.md)
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event for which to remove all listeners.
#### Returns
`void`
#### Inherited from
[`EventEmitter`](../../Core/classes/EventEmitter.md).[`removeAllListeners`](../../Core/classes/EventEmitter.md#removealllisteners)
***
### removeEventListener()
> **removeEventListener**\<`K`\>(`type`, `listener`): `void`
Removes an event listener previously registered with addEventListener.
#### Type Parameters
• **K** *extends* keyof [`DocumentViewEventMap`](../interfaces/DocumentViewEventMap.md)
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event for which to remove an event listener.
• **listener**
The event listener function of the event handler to remove from the event target.
#### Returns
`void`
#### Inherited from
[`EventEmitter`](../../Core/classes/EventEmitter.md).[`removeEventListener`](../../Core/classes/EventEmitter.md#removeeventlistener)
---
## Class: DocumentViewPage
Represents a page in the document view, containing multiple layers for rendering page images, search results, and interactive elements.
## Constructors
### new DocumentViewPage()
> **new DocumentViewPage**(`documentView`, `pageNumber`): [`DocumentViewPage`](DocumentViewPage.md)
Creates an instance of DocumentViewPage.
#### Parameters
• **documentView**: [`DocumentView`](DocumentView.md)
The parent document view.
• **pageNumber**: `number`
The page number.
#### Returns
[`DocumentViewPage`](DocumentViewPage.md)
## Accessors
### accessibilityLayer
> `get` **accessibilityLayer**(): [`AccessibilityLayer`](AccessibilityLayer.md)
Retrieves the accessibility layer.
This layer contains invisible HTML elements aligned with the text fragments for accessibility purposes.
#### Returns
[`AccessibilityLayer`](AccessibilityLayer.md)
***
### container
> `get` **container**(): `HTMLDivElement`
Gets the container element.
#### Returns
`HTMLDivElement`
***
### documentView
> `get` **documentView**(): [`DocumentView`](DocumentView.md)
Gets the associated document view.
#### Returns
[`DocumentView`](DocumentView.md)
***
### image
> `set` **image**(`v`): `void`
Sets the page image data for the page and updates the image layer.
#### Parameters
• **v**: [`Image`](../interfaces/Image.md)
The new image data.
***
### interactiveLayers
> `get` **interactiveLayers**(): [`Layer`](Layer.md)\<[`LayerNativeElementType`](../type-aliases/LayerNativeElementType.md)\>[]
Gets the array of interactive layers.
> `set` **interactiveLayers**(`v`): `void`
Sets the interactive layers, updating their placement within the container.
Each layer's size is updated to match the page size and the container is refreshed
to maintain the correct layer stacking order.
#### Parameters
• **v**: [`Layer`](Layer.md)\<[`LayerNativeElementType`](../type-aliases/LayerNativeElementType.md)\>[]
#### Returns
[`Layer`](Layer.md)\<[`LayerNativeElementType`](../type-aliases/LayerNativeElementType.md)\>[]
***
### origin
> `get` **origin**(): `DocumentViewPoint`
Gets the origin point of the page.
> `set` **origin**(`v`): `void`
Sets the origin of the page and updates its position within the document view.
#### Parameters
• **v**: `DocumentViewPoint`
The new origin point.
#### Returns
`DocumentViewPoint`
***
### pageImageLayer
> `get` **pageImageLayer**(): [`PageImageLayer`](PageImageLayer.md)
Gets the page image layer.
#### Returns
[`PageImageLayer`](PageImageLayer.md)
***
### pageNumber
> `get` **pageNumber**(): `number`
Gets the page number.
#### Returns
`number`
***
### searchResultsLayer
> `get` **searchResultsLayer**(): [`SearchResultsLayer`](SearchResultsLayer.md)
Gets the search results layer.
> `set` **searchResultsLayer**(`v`): `void`
Sets the search results layer and updates its size.
#### Parameters
• **v**: [`SearchResultsLayer`](SearchResultsLayer.md)
#### Returns
[`SearchResultsLayer`](SearchResultsLayer.md)
***
### size
> `get` **size**(): [`Size`](../../Pdf/namespaces/Geometry/classes/Size.md)
Gets the size of the page.
> `set` **size**(`v`): `void`
Sets the size of the page and updates the dimensions of associated layers.
#### Parameters
• **v**: [`Size`](../../Pdf/namespaces/Geometry/classes/Size.md)
The new size of the page.
#### Returns
[`Size`](../../Pdf/namespaces/Geometry/classes/Size.md)
## Methods
### appendAllLayers()
> **appendAllLayers**(): `void`
Appends the various layers (page image, search results, interactive, and accessibility layers)
to the container element of the document view page.
This method ensures that the layers are added in the correct order:
1. The page image layer is added first, as it serves as the base layer.
2. The search results layer is added on top of the page image layer.
3. The interactive layers, if present, are added next to handle user interactions.
4. The accessibility layer, if enabled, is added last to provide accessibility features.
#### Returns
`void`
---
## Class: `abstract` Layer\
Abstract base class for a Layer, which is an event emitter that renders on a native HTML element.
## Extends
- [`EventEmitter`](../../Core/classes/EventEmitter.md)\<[`LayerEventMap`](../interfaces/LayerEventMap.md)\>
## Extended by
- [`PageImageLayer`](PageImageLayer.md)
- [`SearchResultsLayer`](SearchResultsLayer.md)
- [`AccessibilityLayer`](AccessibilityLayer.md)
- [`TextSelectionLayer`](TextSelectionLayer.md)
## Type Parameters
• **T** *extends* [`LayerNativeElementType`](../type-aliases/LayerNativeElementType.md)
The type of the native element, either `HTMLDivElement` or `HTMLCanvasElement`.
## Constructors
### new Layer()
> **new Layer**\<`T`\>(`id`, `documentViewPage`): [`Layer`](Layer.md)\<`T`\>
Creates an instance of Layer.
#### Parameters
• **id**: `string`
The unique identifier for the layer.
• **documentViewPage**: [`DocumentViewPage`](DocumentViewPage.md)
The associated document view page.
#### Returns
[`Layer`](Layer.md)\<`T`\>
#### Overrides
[`EventEmitter`](../../Core/classes/EventEmitter.md).[`constructor`](../../Core/classes/EventEmitter.md#constructors)
## Accessors
### documentViewPage
> `get` **documentViewPage**(): [`DocumentViewPage`](DocumentViewPage.md)
Gets the document view page associated with this layer.
#### Returns
[`DocumentViewPage`](DocumentViewPage.md)
***
### id
> `get` **id**(): `string`
Gets the unique identifier of the layer.
#### Returns
`string`
***
### nativeElement
> `get` **nativeElement**(): `T`
Gets the native HTML element of this layer.
#### Returns
`T`
***
### size
> `get` **size**(): [`Size`](../../Pdf/namespaces/Geometry/classes/Size.md)
Gets the size of the layer.
> `set` **size**(`v`): `void`
Sets the size of the layer and dispatches a size change event if the size is different.
#### Parameters
• **v**: [`Size`](../../Pdf/namespaces/Geometry/classes/Size.md)
The new size to be set.
#### Returns
[`Size`](../../Pdf/namespaces/Geometry/classes/Size.md)
## Methods
### addEventListener()
> **addEventListener**\<`K`\>(`type`, `listener`): `void`
Register a function that will be called whenever the specified event is delivered.
#### Type Parameters
• **K** *extends* `"sizeChanged"`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event type to listen for.
• **listener**
The function that will be executed when an event of the specified type occurs.
#### Returns
`void`
#### Inherited from
[`EventEmitter`](../../Core/classes/EventEmitter.md).[`addEventListener`](../../Core/classes/EventEmitter.md#addeventlistener)
***
### dispatchEvent()
> **dispatchEvent**\<`K`\>(`type`, `args`): `void`
Dispatches an event to all registered listeners.
#### Type Parameters
• **K** *extends* `"sizeChanged"`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event type to dispatch.
• **args**: `Parameters`\<[`LayerEventMap`](../interfaces/LayerEventMap.md)\[`K`\]\>
The data associated with the event.
#### Returns
`void`
#### Inherited from
[`EventEmitter`](../../Core/classes/EventEmitter.md).[`dispatchEvent`](../../Core/classes/EventEmitter.md#dispatchevent)
***
### removeAllListeners()
> **removeAllListeners**\<`K`\>(`type`): `void`
Remove all listeners for a given event.
#### Type Parameters
• **K** *extends* `"sizeChanged"`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event for which to remove all listeners.
#### Returns
`void`
#### Inherited from
[`EventEmitter`](../../Core/classes/EventEmitter.md).[`removeAllListeners`](../../Core/classes/EventEmitter.md#removealllisteners)
***
### removeEventListener()
> **removeEventListener**\<`K`\>(`type`, `listener`): `void`
Removes an event listener previously registered with addEventListener.
#### Type Parameters
• **K** *extends* `"sizeChanged"`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event for which to remove an event listener.
• **listener**
The event listener function of the event handler to remove from the event target.
#### Returns
`void`
#### Inherited from
[`EventEmitter`](../../Core/classes/EventEmitter.md).[`removeEventListener`](../../Core/classes/EventEmitter.md#removeeventlistener)
---
## Class: PageImageLayer
Represents a layer that renders an page image on a canvas.
## Extends
- [`Layer`](Layer.md)\<`HTMLCanvasElement`\>
## Constructors
### new PageImageLayer()
> **new PageImageLayer**(`id`, `documentViewPage`): [`PageImageLayer`](PageImageLayer.md)
Creates an instance of Layer.
#### Parameters
• **id**: `string`
The unique identifier for the layer.
• **documentViewPage**: [`DocumentViewPage`](DocumentViewPage.md)
The associated document view page.
#### Returns
[`PageImageLayer`](PageImageLayer.md)
#### Inherited from
[`Layer`](Layer.md).[`constructor`](Layer.md#constructors)
## Accessors
### documentViewPage
> `get` **documentViewPage**(): [`DocumentViewPage`](DocumentViewPage.md)
Gets the document view page associated with this layer.
#### Returns
[`DocumentViewPage`](DocumentViewPage.md)
#### Inherited from
[`Layer`](Layer.md).[`documentViewPage`](Layer.md#documentviewpage)
***
### id
> `get` **id**(): `string`
Gets the unique identifier of the layer.
#### Returns
`string`
#### Inherited from
[`Layer`](Layer.md).[`id`](Layer.md#id)
***
### image
> `set` **image**(`v`): `void`
Sets the page image data and triggers rendering.
#### Parameters
• **v**: [`Image`](../interfaces/Image.md)
The new image data.
***
### nativeElement
> `get` **nativeElement**(): `T`
Gets the native HTML element of this layer.
#### Returns
`T`
#### Inherited from
[`Layer`](Layer.md).[`nativeElement`](Layer.md#nativeelement)
***
### size
> `get` **size**(): [`Size`](../../Pdf/namespaces/Geometry/classes/Size.md)
Gets the size of the layer.
> `set` **size**(`v`): `void`
Sets the size of the layer and dispatches a size change event if the size is different.
#### Parameters
• **v**: [`Size`](../../Pdf/namespaces/Geometry/classes/Size.md)
The new size to be set.
#### Returns
[`Size`](../../Pdf/namespaces/Geometry/classes/Size.md)
#### Inherited from
[`Layer`](Layer.md).[`size`](Layer.md#size)
## Methods
### addEventListener()
> **addEventListener**\<`K`\>(`type`, `listener`): `void`
Register a function that will be called whenever the specified event is delivered.
#### Type Parameters
• **K** *extends* `"sizeChanged"`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event type to listen for.
• **listener**
The function that will be executed when an event of the specified type occurs.
#### Returns
`void`
#### Inherited from
[`Layer`](Layer.md).[`addEventListener`](Layer.md#addeventlistener)
***
### dispatchEvent()
> **dispatchEvent**\<`K`\>(`type`, `args`): `void`
Dispatches an event to all registered listeners.
#### Type Parameters
• **K** *extends* `"sizeChanged"`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event type to dispatch.
• **args**: `Parameters`\<[`LayerEventMap`](../interfaces/LayerEventMap.md)\[`K`\]\>
The data associated with the event.
#### Returns
`void`
#### Inherited from
[`Layer`](Layer.md).[`dispatchEvent`](Layer.md#dispatchevent)
***
### removeAllListeners()
> **removeAllListeners**\<`K`\>(`type`): `void`
Remove all listeners for a given event.
#### Type Parameters
• **K** *extends* `"sizeChanged"`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event for which to remove all listeners.
#### Returns
`void`
#### Inherited from
[`Layer`](Layer.md).[`removeAllListeners`](Layer.md#removealllisteners)
***
### removeEventListener()
> **removeEventListener**\<`K`\>(`type`, `listener`): `void`
Removes an event listener previously registered with addEventListener.
#### Type Parameters
• **K** *extends* `"sizeChanged"`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event for which to remove an event listener.
• **listener**
The event listener function of the event handler to remove from the event target.
#### Returns
`void`
#### Inherited from
[`Layer`](Layer.md).[`removeEventListener`](Layer.md#removeeventlistener)
---
## Class: PluginManager
Manages a collection of plugins, allowing registration, activation, and deactivation.
## Constructors
### new PluginManager()
> **new PluginManager**(): [`PluginManager`](PluginManager.md)
#### Returns
[`PluginManager`](PluginManager.md)
## Accessors
### documentView
> `get` **documentView**(): [`DocumentView`](DocumentView.md)
Gets the current document view.
> `set` **documentView**(`v`): `void`
Sets a new document view and updates all registered plugins with the new view.
Deactivates each plugin before assigning the new view.
#### Parameters
• **v**: [`DocumentView`](DocumentView.md)
#### Returns
[`DocumentView`](DocumentView.md)
## Methods
### activatePlugin()
> **activatePlugin**(`plugin`): `void`
Activates a given plugin and deactivates all other plugins.
#### Parameters
• **plugin**: [`Plugin`](../interfaces/Plugin.md)
The plugin to activate.
#### Returns
`void`
***
### activatePluginById()
> **activatePluginById**(`pluginId`): `void`
Activates a plugin by its ID and deactivates all other plugins.
#### Parameters
• **pluginId**: `string`
The ID of the plugin to activate.
#### Returns
`void`
#### Throws
If the plugin with the given ID does not exist.
***
### deregisterPlugin()
> **deregisterPlugin**(`plugin`): `void`
Deregisters a plugin and deactivates it.
#### Parameters
• **plugin**: [`Plugin`](../interfaces/Plugin.md)
The plugin to deregister.
#### Returns
`void`
***
### deregisterPluginById()
> **deregisterPluginById**(`pluginId`): `void`
Deregisters a plugin by its ID.
#### Parameters
• **pluginId**: `string`
The ID of the plugin to deregister.
#### Returns
`void`
#### Throws
If the plugin with the given ID does not exist.
***
### getPluginById()
> **getPluginById**(`id`): [`Plugin`](../interfaces/Plugin.md)
Retrieves a plugin by its ID.
#### Parameters
• **id**: `string`
The ID of the plugin to retrieve.
#### Returns
[`Plugin`](../interfaces/Plugin.md)
The plugin with the given ID, or undefined if not found.
***
### registerPlugin()
> **registerPlugin**(`plugin`): `void`
Registers a new plugin.
#### Parameters
• **plugin**: [`Plugin`](../interfaces/Plugin.md)
The plugin to register.
#### Returns
`void`
#### Throws
If a plugin with the same ID is already registered.
---
## Class: SearchResultsLayer
Represents a layer that highlights search results on a PDF document.
## Extends
- [`Layer`](Layer.md)\<`HTMLCanvasElement`\>
## Constructors
### new SearchResultsLayer()
> **new SearchResultsLayer**(`id`, `documentViewPage`): [`SearchResultsLayer`](SearchResultsLayer.md)
Creates an instance of Layer.
#### Parameters
• **id**: `string`
The unique identifier for the layer.
• **documentViewPage**: [`DocumentViewPage`](DocumentViewPage.md)
The associated document view page.
#### Returns
[`SearchResultsLayer`](SearchResultsLayer.md)
#### Inherited from
[`Layer`](Layer.md).[`constructor`](Layer.md#constructors)
## Accessors
### activeSearchResult
> `set` **activeSearchResult**(`v`): `void`
Sets the active search result and triggers rendering.
#### Parameters
• **v**: [`DocumentTextSearchResult`](../../Pdf/namespaces/Search/interfaces/DocumentTextSearchResult.md)
The active search result.
***
### documentViewPage
> `get` **documentViewPage**(): [`DocumentViewPage`](DocumentViewPage.md)
Gets the document view page associated with this layer.
#### Returns
[`DocumentViewPage`](DocumentViewPage.md)
#### Inherited from
[`Layer`](Layer.md).[`documentViewPage`](Layer.md#documentviewpage)
***
### id
> `get` **id**(): `string`
Gets the unique identifier of the layer.
#### Returns
`string`
#### Inherited from
[`Layer`](Layer.md).[`id`](Layer.md#id)
***
### nativeElement
> `get` **nativeElement**(): `T`
Gets the native HTML element of this layer.
#### Returns
`T`
#### Inherited from
[`Layer`](Layer.md).[`nativeElement`](Layer.md#nativeelement)
***
### searchResults
> `set` **searchResults**(`v`): `void`
Sets the search results and triggers rendering.
#### Parameters
• **v**: [`DocumentTextSearchResult`](../../Pdf/namespaces/Search/interfaces/DocumentTextSearchResult.md)[]
The new search results.
***
### size
> `get` **size**(): [`Size`](../../Pdf/namespaces/Geometry/classes/Size.md)
Gets the size of the layer.
> `set` **size**(`v`): `void`
Sets the size of the layer and dispatches a size change event if the size is different.
#### Parameters
• **v**: [`Size`](../../Pdf/namespaces/Geometry/classes/Size.md)
The new size to be set.
#### Returns
[`Size`](../../Pdf/namespaces/Geometry/classes/Size.md)
#### Inherited from
[`Layer`](Layer.md).[`size`](Layer.md#size)
## Methods
### addEventListener()
> **addEventListener**\<`K`\>(`type`, `listener`): `void`
Register a function that will be called whenever the specified event is delivered.
#### Type Parameters
• **K** *extends* `"sizeChanged"`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event type to listen for.
• **listener**
The function that will be executed when an event of the specified type occurs.
#### Returns
`void`
#### Inherited from
[`Layer`](Layer.md).[`addEventListener`](Layer.md#addeventlistener)
***
### dispatchEvent()
> **dispatchEvent**\<`K`\>(`type`, `args`): `void`
Dispatches an event to all registered listeners.
#### Type Parameters
• **K** *extends* `"sizeChanged"`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event type to dispatch.
• **args**: `Parameters`\<[`LayerEventMap`](../interfaces/LayerEventMap.md)\[`K`\]\>
The data associated with the event.
#### Returns
`void`
#### Inherited from
[`Layer`](Layer.md).[`dispatchEvent`](Layer.md#dispatchevent)
***
### removeAllListeners()
> **removeAllListeners**\<`K`\>(`type`): `void`
Remove all listeners for a given event.
#### Type Parameters
• **K** *extends* `"sizeChanged"`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event for which to remove all listeners.
#### Returns
`void`
#### Inherited from
[`Layer`](Layer.md).[`removeAllListeners`](Layer.md#removealllisteners)
***
### removeEventListener()
> **removeEventListener**\<`K`\>(`type`, `listener`): `void`
Removes an event listener previously registered with addEventListener.
#### Type Parameters
• **K** *extends* `"sizeChanged"`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event for which to remove an event listener.
• **listener**
The event listener function of the event handler to remove from the event target.
#### Returns
`void`
#### Inherited from
[`Layer`](Layer.md).[`removeEventListener`](Layer.md#removeeventlistener)
---
## Class: TextSelectionLayer
Abstract base class for a Layer, which is an event emitter that renders on a native HTML element.
## Extends
- [`Layer`](Layer.md)\<`HTMLCanvasElement`\>
## Constructors
### new TextSelectionLayer()
> **new TextSelectionLayer**(`id`, `documentViewPage`): [`TextSelectionLayer`](TextSelectionLayer.md)
Creates an instance of Layer.
#### Parameters
• **id**: `string`
The unique identifier for the layer.
• **documentViewPage**: [`DocumentViewPage`](DocumentViewPage.md)
The associated document view page.
#### Returns
[`TextSelectionLayer`](TextSelectionLayer.md)
#### Inherited from
[`Layer`](Layer.md).[`constructor`](Layer.md#constructors)
## Accessors
### documentViewPage
> `get` **documentViewPage**(): [`DocumentViewPage`](DocumentViewPage.md)
Gets the document view page associated with this layer.
#### Returns
[`DocumentViewPage`](DocumentViewPage.md)
#### Inherited from
[`Layer`](Layer.md).[`documentViewPage`](Layer.md#documentviewpage)
***
### id
> `get` **id**(): `string`
Gets the unique identifier of the layer.
#### Returns
`string`
#### Inherited from
[`Layer`](Layer.md).[`id`](Layer.md#id)
***
### nativeElement
> `get` **nativeElement**(): `T`
Gets the native HTML element of this layer.
#### Returns
`T`
#### Inherited from
[`Layer`](Layer.md).[`nativeElement`](Layer.md#nativeelement)
***
### size
> `get` **size**(): [`Size`](../../Pdf/namespaces/Geometry/classes/Size.md)
Gets the size of the layer.
> `set` **size**(`v`): `void`
Sets the size of the layer and dispatches a size change event if the size is different.
#### Parameters
• **v**: [`Size`](../../Pdf/namespaces/Geometry/classes/Size.md)
The new size to be set.
#### Returns
[`Size`](../../Pdf/namespaces/Geometry/classes/Size.md)
#### Inherited from
[`Layer`](Layer.md).[`size`](Layer.md#size)
## Methods
### addEventListener()
> **addEventListener**\<`K`\>(`type`, `listener`): `void`
Register a function that will be called whenever the specified event is delivered.
#### Type Parameters
• **K** *extends* `"sizeChanged"`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event type to listen for.
• **listener**
The function that will be executed when an event of the specified type occurs.
#### Returns
`void`
#### Inherited from
[`Layer`](Layer.md).[`addEventListener`](Layer.md#addeventlistener)
***
### dispatchEvent()
> **dispatchEvent**\<`K`\>(`type`, `args`): `void`
Dispatches an event to all registered listeners.
#### Type Parameters
• **K** *extends* `"sizeChanged"`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event type to dispatch.
• **args**: `Parameters`\<[`LayerEventMap`](../interfaces/LayerEventMap.md)\[`K`\]\>
The data associated with the event.
#### Returns
`void`
#### Inherited from
[`Layer`](Layer.md).[`dispatchEvent`](Layer.md#dispatchevent)
***
### removeAllListeners()
> **removeAllListeners**\<`K`\>(`type`): `void`
Remove all listeners for a given event.
#### Type Parameters
• **K** *extends* `"sizeChanged"`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event for which to remove all listeners.
#### Returns
`void`
#### Inherited from
[`Layer`](Layer.md).[`removeAllListeners`](Layer.md#removealllisteners)
***
### removeEventListener()
> **removeEventListener**\<`K`\>(`type`, `listener`): `void`
Removes an event listener previously registered with addEventListener.
#### Type Parameters
• **K** *extends* `"sizeChanged"`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event for which to remove an event listener.
• **listener**
The event listener function of the event handler to remove from the event target.
#### Returns
`void`
#### Inherited from
[`Layer`](Layer.md).[`removeEventListener`](Layer.md#removeeventlistener)
---
## Class: TextSelectionPlugin
Represents a plugin that can be registered, activated, and deactivated.
## Extends
- [`EventEmitter`](../../Core/classes/EventEmitter.md)\<[`TextSelectionPluginEventMap`](../interfaces/TextSelectionPluginEventMap.md)\>
## Implements
- [`Plugin`](../interfaces/Plugin.md)
## Constructors
### new TextSelectionPlugin()
> **new TextSelectionPlugin**(`documentView`): [`TextSelectionPlugin`](TextSelectionPlugin.md)
#### Parameters
• **documentView**: [`DocumentView`](DocumentView.md)
#### Returns
[`TextSelectionPlugin`](TextSelectionPlugin.md)
#### Overrides
[`EventEmitter`](../../Core/classes/EventEmitter.md).[`constructor`](../../Core/classes/EventEmitter.md#constructors)
## Properties
### id
> **id**: `string` = `'text-selection-plugin'`
Unique identifier for the plugin.
#### Implementation of
[`Plugin`](../interfaces/Plugin.md).[`id`](../interfaces/Plugin.md#id)
## Accessors
### active
> `get` **active**(): `boolean`
> `set` **active**(`v`): `void`
#### Parameters
• **v**: `boolean`
#### Returns
`boolean`
***
### debugMode
> `get` **debugMode**(): `boolean`
> `set` **debugMode**(`v`): `void`
#### Parameters
• **v**: `boolean`
#### Returns
`boolean`
***
### documentView
> `get` **documentView**(): [`DocumentView`](DocumentView.md)
The document view associated with the plugin.
> `set` **documentView**(`v`): `void`
The document view associated with the plugin.
#### Parameters
• **v**: [`DocumentView`](DocumentView.md)
#### Returns
[`DocumentView`](DocumentView.md)
The document view associated with the plugin.
#### Implementation of
[`Plugin`](../interfaces/Plugin.md).[`documentView`](../interfaces/Plugin.md#documentview)
## Methods
### activate()
> **activate**(): `void`
Activates the plugin.
#### Returns
`void`
#### Implementation of
[`Plugin`](../interfaces/Plugin.md).[`activate`](../interfaces/Plugin.md#activate)
***
### addEventListener()
> **addEventListener**\<`K`\>(`type`, `listener`): `void`
Register a function that will be called whenever the specified event is delivered.
#### Type Parameters
• **K** *extends* `"textSelectionChanged"`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event type to listen for.
• **listener**
The function that will be executed when an event of the specified type occurs.
#### Returns
`void`
#### Inherited from
[`EventEmitter`](../../Core/classes/EventEmitter.md).[`addEventListener`](../../Core/classes/EventEmitter.md#addeventlistener)
***
### deactivate()
> **deactivate**(): `void`
Deactivates the plugin.
#### Returns
`void`
#### Implementation of
[`Plugin`](../interfaces/Plugin.md).[`deactivate`](../interfaces/Plugin.md#deactivate)
***
### dispatchEvent()
> **dispatchEvent**\<`K`\>(`type`, `args`): `void`
Dispatches an event to all registered listeners.
#### Type Parameters
• **K** *extends* `"textSelectionChanged"`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event type to dispatch.
• **args**: `Parameters`\<[`TextSelectionPluginEventMap`](../interfaces/TextSelectionPluginEventMap.md)\[`K`\]\>
The data associated with the event.
#### Returns
`void`
#### Inherited from
[`EventEmitter`](../../Core/classes/EventEmitter.md).[`dispatchEvent`](../../Core/classes/EventEmitter.md#dispatchevent)
***
### removeAllListeners()
> **removeAllListeners**\<`K`\>(`type`): `void`
Remove all listeners for a given event.
#### Type Parameters
• **K** *extends* `"textSelectionChanged"`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event for which to remove all listeners.
#### Returns
`void`
#### Inherited from
[`EventEmitter`](../../Core/classes/EventEmitter.md).[`removeAllListeners`](../../Core/classes/EventEmitter.md#removealllisteners)
***
### removeEventListener()
> **removeEventListener**\<`K`\>(`type`, `listener`): `void`
Removes an event listener previously registered with addEventListener.
#### Type Parameters
• **K** *extends* `"textSelectionChanged"`
A generic type representing the key of the event type.
#### Parameters
• **type**: `K`
String representing the event for which to remove an event listener.
• **listener**
The event listener function of the event handler to remove from the event target.
#### Returns
`void`
#### Inherited from
[`EventEmitter`](../../Core/classes/EventEmitter.md).[`removeEventListener`](../../Core/classes/EventEmitter.md#removeeventlistener)
---
## Function: drawTextSelectionInfo()
> **drawTextSelectionInfo**(`documentView`, `textSelectionInfo`, `debugMode`): `void`
## Parameters
• **documentView**: [`DocumentView`](../classes/DocumentView.md)
• **textSelectionInfo**: `TextSelectionInfo`
• **debugMode**: `boolean` = `false`
## Returns
`void`
---
## Function: drawTextSelectionInfoDebug()
> **drawTextSelectionInfoDebug**(`documentView`, `textSelectionInfo`): `void`
## Parameters
• **documentView**: [`DocumentView`](../classes/DocumentView.md)
• **textSelectionInfo**: `TextSelectionInfo`
## Returns
`void`
---
## UI
## Index
### Classes
- [AccessibilityLayer](classes/AccessibilityLayer.md)
- [DocumentView](classes/DocumentView.md)
- [DocumentViewPage](classes/DocumentViewPage.md)
- [Layer](classes/Layer.md)
- [PageImageLayer](classes/PageImageLayer.md)
- [PluginManager](classes/PluginManager.md)
- [SearchResultsLayer](classes/SearchResultsLayer.md)
- [TextSelectionLayer](classes/TextSelectionLayer.md)
- [TextSelectionPlugin](classes/TextSelectionPlugin.md)
### Interfaces
- [DocumentViewEventMap](interfaces/DocumentViewEventMap.md)
- [Image](interfaces/Image.md)
- [LayerEventMap](interfaces/LayerEventMap.md)
- [Plugin](interfaces/Plugin.md)
- [TextSelectionPluginEventMap](interfaces/TextSelectionPluginEventMap.md)
### Type Aliases
- [DocumentViewOptions](type-aliases/DocumentViewOptions.md)
- [LayerNativeElementType](type-aliases/LayerNativeElementType.md)
### Functions
- [drawTextSelectionInfo](functions/drawTextSelectionInfo.md)
- [drawTextSelectionInfoDebug](functions/drawTextSelectionInfoDebug.md)
---
## Interface: DocumentViewEventMap
Interface defining event types for changes in a document view.
## Properties
### currentPageChanged()
> **currentPageChanged**: (`pageNumber`) => `void`
Event triggered when the currently displayed page in the document view changes.
The event payload is a number representing the page number of the currently displayed page.
#### Parameters
• **pageNumber**: `number`
#### Returns
`void`
***
### documentViewClick()
> **documentViewClick**: (`payload`) => `void`
Event triggered when the document view is clicked.
The event payload is the MouseEvent object.
#### Parameters
• **payload**: `MouseEvent`
#### Returns
`void`
***
### documentViewDoubleClick()
> **documentViewDoubleClick**: (`payload`) => `void`
Event triggered when the document view is double-clicked.
The event payload is the MouseEvent object.
#### Parameters
• **payload**: `MouseEvent`
#### Returns
`void`
***
### documentViewMouseDown()
> **documentViewMouseDown**: (`payload`) => `void`
Event triggered when the mouse button is pressed down within the document view.
The event payload is the MouseEvent object.
#### Parameters
• **payload**: `MouseEvent`
#### Returns
`void`
***
### documentViewMouseEnter()
> **documentViewMouseEnter**: (`payload`) => `void`
Event triggered when the mouse enters the document view.
The event payload is the MouseEvent object.
#### Parameters
• **payload**: `MouseEvent`
#### Returns
`void`
***
### documentViewMouseLeave()
> **documentViewMouseLeave**: (`payload`) => `void`
Event triggered when the mouse leaves the document view.
The event payload is the MouseEvent object.
#### Parameters
• **payload**: `MouseEvent`
#### Returns
`void`
***
### documentViewMouseMove()
> **documentViewMouseMove**: (`payload`) => `void`
Event triggered when the mouse moves within the document view.
The event payload is the MouseEvent object.
#### Parameters
• **payload**: `MouseEvent`
#### Returns
`void`
***
### documentViewMouseUp()
> **documentViewMouseUp**: (`payload`) => `void`
Event triggered when the mouse button is released within the document view.
The event payload is the MouseEvent object.
#### Parameters
• **payload**: `MouseEvent`
#### Returns
`void`
***
### documentViewPointerCancel()
> **documentViewPointerCancel**: (`event`) => `void`
Fired when a pointer is canceled (e.g. touch→pointercancel) in the document view.
#### Parameters
• **event**: `PointerEvent`
#### Returns
`void`
***
### documentViewPointerDown()
> **documentViewPointerDown**: (`event`) => `void`
Fired when a pointer is pressed down anywhere in the document view.
#### Parameters
• **event**: `PointerEvent`
#### Returns
`void`
***
### documentViewPointerEnter()
> **documentViewPointerEnter**: (`event`) => `void`
Fired when a pointer enters the document view.
#### Parameters
• **event**: `PointerEvent`
#### Returns
`void`
***
### documentViewPointerLeave()
> **documentViewPointerLeave**: (`event`) => `void`
Fired when a pointer leaves the document view.
#### Parameters
• **event**: `PointerEvent`
#### Returns
`void`
***
### documentViewPointerMove()
> **documentViewPointerMove**: (`event`) => `void`
Fired when a pointer moves within the document view.
#### Parameters
• **event**: `PointerEvent`
#### Returns
`void`
***
### documentViewPointerUp()
> **documentViewPointerUp**: (`event`) => `void`
Fired when a pointer is released anywhere in the document view.
#### Parameters
• **event**: `PointerEvent`
#### Returns
`void`
***
### documentViewTouchCancel()
> **documentViewTouchCancel**: (`payload`) => `void`
Event triggered when a touch is canceled within the document view.
The event payload is the TouchEvent object.
#### Parameters
• **payload**: `TouchEvent`
#### Returns
`void`
***
### documentViewTouchEnd()
> **documentViewTouchEnd**: (`payload`) => `void`
Event triggered when a touch ends within the document view.
The event payload is the TouchEvent object.
#### Parameters
• **payload**: `TouchEvent`
#### Returns
`void`
***
### documentViewTouchMove()
> **documentViewTouchMove**: (`payload`) => `void`
Event triggered when a touch moves within the document view.
The event payload is the TouchEvent object.
#### Parameters
• **payload**: `TouchEvent`
#### Returns
`void`
***
### documentViewTouchStart()
> **documentViewTouchStart**: (`payload`) => `void`
Event triggered when a touch starts within the document view.
The event payload is the TouchEvent object.
#### Parameters
• **payload**: `TouchEvent`
#### Returns
`void`
***
### firstVisiblePageChanged()
> **firstVisiblePageChanged**: (`pageNumber`) => `void`
Event triggered when the index of the first visible page in the document view changes.
The event payload is a number representing the page number of the first visible page.
#### Parameters
• **pageNumber**: `number`
#### Returns
`void`
***
### fitModeChanged()
> **fitModeChanged**: (`fitMode`) => `void`
Event triggered when the fit mode of the document view changes.
The event payload is a value of the FitMode enum representing the new fit mode.
#### Parameters
• **fitMode**: [`FitMode`](../../Pdf/enumerations/FitMode.md)
#### Returns
`void`
***
### lastVisiblePageChanged()
> **lastVisiblePageChanged**: (`pageNumber`) => `void`
Event triggered when the index of the last visible page in the document view changes.
The event payload is a number representing the page number of the last visible page.
#### Parameters
• **pageNumber**: `number`
#### Returns
`void`
***
### pageAddedToViewport()
> **pageAddedToViewport**: (`pageNumber`) => `void`
#### Parameters
• **pageNumber**: `number`
#### Returns
`void`
***
### pageClick()
> **pageClick**: (`pageNumber`, `payload`) => `void`
#### Parameters
• **pageNumber**: `number`
• **payload**: `MouseEvent`
#### Returns
`void`
***
### pageDoubleClick()
> **pageDoubleClick**: (`pageNumber`, `payload`) => `void`
#### Parameters
• **pageNumber**: `number`
• **payload**: `MouseEvent`
#### Returns
`void`
***
### pageLayoutModeChanged()
> **pageLayoutModeChanged**: (`pageLayoutMode`) => `void`
Event triggered when the page layout mode of the document view changes.
The event payload is a value of the PageLayoutMode enum representing the new layout mode.
#### Parameters
• **pageLayoutMode**: [`PageLayoutMode`](../../Pdf/enumerations/PageLayoutMode.md)
#### Returns
`void`
***
### pageMouseDown()
> **pageMouseDown**: (`pageNumber`, `payload`) => `void`
#### Parameters
• **pageNumber**: `number`
• **payload**: `MouseEvent`
#### Returns
`void`
***
### pageMouseEnter()
> **pageMouseEnter**: (`pageNumber`, `payload`) => `void`
#### Parameters
• **pageNumber**: `number`
• **payload**: `MouseEvent`
#### Returns
`void`
***
### pageMouseLeave()
> **pageMouseLeave**: (`pageNumber`, `payload`) => `void`
#### Parameters
• **pageNumber**: `number`
• **payload**: `MouseEvent`
#### Returns
`void`
***
### pageMouseMove()
> **pageMouseMove**: (`pageNumber`, `payload`) => `void`
#### Parameters
• **pageNumber**: `number`
• **payload**: `MouseEvent`
#### Returns
`void`
***
### pageMouseUp()
> **pageMouseUp**: (`pageNumber`, `payload`) => `void`
#### Parameters
• **pageNumber**: `number`
• **payload**: `MouseEvent`
#### Returns
`void`
***
### pagePointerCancel()
> **pagePointerCancel**: (`pageNumber`, `payload`) => `void`
#### Parameters
• **pageNumber**: `number`
• **payload**: `PointerEvent`
#### Returns
`void`
***
### pagePointerDown()
> **pagePointerDown**: (`pageNumber`, `payload`) => `void`
#### Parameters
• **pageNumber**: `number`
• **payload**: `PointerEvent`
#### Returns
`void`
***
### pagePointerEnter()
> **pagePointerEnter**: (`pageNumber`, `payload`) => `void`
#### Parameters
• **pageNumber**: `number`
• **payload**: `PointerEvent`
#### Returns
`void`
***
### pagePointerLeave()
> **pagePointerLeave**: (`pageNumber`, `payload`) => `void`
#### Parameters
• **pageNumber**: `number`
• **payload**: `PointerEvent`
#### Returns
`void`
***
### pagePointerMove()
> **pagePointerMove**: (`pageNumber`, `payload`) => `void`
#### Parameters
• **pageNumber**: `number`
• **payload**: `PointerEvent`
#### Returns
`void`
***
### pagePointerUp()
> **pagePointerUp**: (`pageNumber`, `payload`) => `void`
#### Parameters
• **pageNumber**: `number`
• **payload**: `PointerEvent`
#### Returns
`void`
***
### pageRemovedFromViewport()
> **pageRemovedFromViewport**: (`pageNumber`) => `void`
#### Parameters
• **pageNumber**: `number`
#### Returns
`void`
***
### pageRendered()
> **pageRendered**: (`pageNumber`) => `void`
Event triggered when a page in the document view finishes rendering.
The event payload is a number representing the page number of the rendered page.
#### Parameters
• **pageNumber**: `number`
#### Returns
`void`
***
### pageTouchCancel()
> **pageTouchCancel**: (`pageNumber`, `payload`) => `void`
#### Parameters
• **pageNumber**: `number`
• **payload**: `TouchEvent`
#### Returns
`void`
***
### pageTouchEnd()
> **pageTouchEnd**: (`pageNumber`, `payload`) => `void`
#### Parameters
• **pageNumber**: `number`
• **payload**: `TouchEvent`
#### Returns
`void`
***
### pageTouchMove()
> **pageTouchMove**: (`pageNumber`, `payload`) => `void`
#### Parameters
• **pageNumber**: `number`
• **payload**: `TouchEvent`
#### Returns
`void`
***
### pageTouchStart()
> **pageTouchStart**: (`pageNumber`, `payload`) => `void`
#### Parameters
• **pageNumber**: `number`
• **payload**: `TouchEvent`
#### Returns
`void`
***
### rotationChanged()
> **rotationChanged**: (`rotation`) => `void`
Event triggered when the rotation of the document view changes.
The event payload is a value of the Rotation enum representing the new rotation.
#### Parameters
• **rotation**: [`Rotation`](../../Pdf/enumerations/Rotation.md)
#### Returns
`void`
***
### scrollPositionChanged()
> **scrollPositionChanged**: (`x`, `y`) => `void`
Event triggered when the scroll in the document view changes.
The event payload is the x,y coordinates of the new scroll position.
#### Parameters
• **x**: `number`
• **y**: `number`
#### Returns
`void`
***
### zoomChanged()
> **zoomChanged**: (`zoomLevel`) => `void`
Event triggered when the zoom level of the document view changes.
The event payload is a number representing the new zoom level.
#### Parameters
• **zoomLevel**: `number`
#### Returns
`void`
---
## Interface: Image
Interface representing the image provided by the PDF renderer.
## Properties
### buffer
> **buffer**: `ArrayBuffer`
***
### height
> **height**: `number`
***
### width
> **width**: `number`
---
## Interface: LayerEventMap
Defines the event map for the Layer class.
## Properties
### sizeChanged()
> **sizeChanged**: (`size`) => `void`
Event triggered when the layer size changes.
#### Parameters
• **size**: [`Size`](../../Pdf/namespaces/Geometry/classes/Size.md)
The new size of the layer.
#### Returns
`void`
---
## Interface: Plugin
Represents a plugin that can be registered, activated, and deactivated.
## Properties
### documentView
> **documentView**: [`DocumentView`](../classes/DocumentView.md)
The document view associated with the plugin.
***
### id
> **id**: `string`
Unique identifier for the plugin.
## Methods
### activate()
> **activate**(): `void`
Activates the plugin.
#### Returns
`void`
***
### deactivate()
> **deactivate**(): `void`
Deactivates the plugin.
#### Returns
`void`
---
## Interface: TextSelectionPluginEventMap
Interface defining event types for changes in a document view.
## Properties
### textSelectionChanged()
> **textSelectionChanged**: (`selectedText`) => `void`
#### Parameters
• **selectedText**: `string`
#### Returns
`void`
---
## Type Alias: DocumentViewOptions
> **DocumentViewOptions**: `object`
Configuration options for initializing a `DocumentView`.
These options allow you to customize the initial behavior and appearance of the document view.
## Type declaration
### accessibilityLayerEnabled?
> `optional` **accessibilityLayerEnabled**: `boolean`
Enables or disables the accessibility layer for the document view.
When enabled, the accessibility layer provides support for screen readers and other accessibility tools
by creating an invisible HTML structure aligned with the text fragments on the page.
#### Default Value
`false`
### dpi?
> `optional` **dpi**: `number`
Specifies the DPI (Dots Per Inch) value for rendering the document.
Higher DPI values result in higher resolution images, making them appear sharper and more detailed.
#### Default Value
`96`
### fitMode?
> `optional` **fitMode**: [`FitMode`](../../Pdf/enumerations/FitMode.md)
Specifies the fit mode for the document view.
Determines how the document pages are scaled to fit within the viewport.
#### Default Value
`FitMode.None`
### pageLayoutMode?
> `optional` **pageLayoutMode**: [`PageLayoutMode`](../../Pdf/enumerations/PageLayoutMode.md)
Specifies the page layout mode for the document view.
Determines how pages are arranged within the viewport (e.g., single column, two columns).
#### Default Value
`PageLayoutMode.OneColumn`
---
## Type Alias: LayerNativeElementType
> **LayerNativeElementType**: `HTMLDivElement` \| `HTMLCanvasElement`
Represents the native element types that a Layer can use.
---
## Type Alias: LicenseKey
> **LicenseKey**: \`\\`
Represents a license key for the Pdftools PDF Web SDK.
The license key is a string that contains the license information.
---
## Variable: pdfToolsWebSdk
> `const` **pdfToolsWebSdk**: `PdfToolsWebSdk`
---
## April 2025
In April 2025, the Pdftools documentation included the following updates:
## Added
- The Pdftools SDK [version 1.9.1](/docs/pdf-tools-sdk/release-notes/#version-191) patch release notes and the Toolbox add-on [version 1.6.1](/docs/pdf-tools-sdk/release-notes/#version-161) patch release notes.
- The Pdftools SDK Shell Tool documentation now includes the [Pdftools SDK Shell Tool 1.7.0](/docs/pdf-tools-sdk/release-notes/#version-170-2) release notes.
- Conversion Service release notes [version 6.1.0](/docs/conversion-service/release-notes/#610). This update also included significant additions and updates for the:
- [Simple API Postman collection](pathname:///files/conversion-service/conversion_service_simple_api.postman_collection.json)
- [Simple API reference](/docs/conversion-service/api/simple-api/simple-api/)
- Added the Conversion Service [version 5.7.5](/docs/conversion-service/release-notes/#575) LTS patch release notes.
- The Conversion Service [Dossier workflow](/docs/conversion-service/workflows/dossier/) page received a major update, including new infographics and many textual improvements.
- Major update of the [Automatic update](/docs/conversion-service/update/docker/#automatic-update) section in the Conversion Service documentation.
- This documentation now includes the PDF Viewer SDK [version 5.5.0](/docs/pdf-web-viewer/release-notes/#version-550) release notes and [API references](/docs/pdf-web-viewer/category/api-references/). Also, the following code snippets and their descriptions were added:
- [Enable accessibility layer](/docs/pdf-web-viewer/standard-implementation/customize-viewer/#enable-accessibility-layer)
- [Provide custom HTTP headers when opening a document](/docs/pdf-web-viewer/standard-implementation/customize-viewer/#provide-custom-http-headers-when-opening-a-document)
## Changed
- Updated descriptions, added images, and improved the style of [PDF Client for Conversion Service](/docs/conversion-service/integrate/gui-client/) page, also the title was changed from PDF Client application (GUI) to **PDF Client for Conversion Service**.
## Fixed
- Structural fixes in the [Connectors](/docs/conversion-service/integrate/connectors/) page.
- Algolia search improvements.
---
## August 2025
In August 2025, the Pdftools documentation included the following updates:
## Added
- 14 new pages that describe custom profile references for the Pdftools OCR Service. Review [Custom profiles](/docs/ocr-service/references/parameters/custom-profiles/) for more details.
- The custom profiles references are split into pages for each [key INI file section](/docs/ocr-service/references/parameters/custom-profiles/#key-ini-file-sections-and-their-purpose).
- You can also use [predefined profiles](/docs/ocr-service/references/parameters/#predefinedprofile) instead of custom profiles.
- Improved the [Scale the Pdftools OCR Service](/docs/ocr-service/guides/scale/) page with added architectural diagrams.
- Conversion Service [version 6.4.1](/docs/conversion-service/release-notes/#641) patch release notes.
- The PDF Viewer SDK [version 4.3.5](/docs/pdf-web-viewer/4/release-notes/#435) patch release.
## Changed
- The links to prerequisites in the Conversion Service on Windows Server getting started guide now directly download the linked packages in the [version 6](/docs/conversion-service/getting-started/windows-server/#prerequisites) and [version 5](/docs/conversion-service/5/getting-started/windows-server/#prerequisites) documentation.
## Fixed
- The PDF Viewer SDK version 5 getting started guide now correctly mentions the `initialize` method instead of incorrectly mentioning `init` in code snippets. This fix has been made in the [Initialize the viewer](/docs/pdf-web-viewer/getting-started/#initialize-the-viewer) section.
- Minor improvements and typo fixes in the [Pdftools OCR Service](/docs/ocr-service/) documentation area.
- In the legacy products, the [Batch Stamp Tool](/docs/other-shell-tools-and-sdks/legacy-products/#batch-stamp-tool) now correctly links to the Toolbox add-on as its replacement.
- Fixed Conversion Service LTS [version 4 API](/docs/conversion-service/4/api/conversion-service/) documentation generation issues.
- Improvements in the [Offline license configuration](/docs/licenses/configure/offline-licensing-gateway-service/#offline-license-configuration) section.
- Improved [llms.txt](https://www.pdf-tools.com/docs/llms.txt) and [llms-full.txt](https://www.pdf-tools.com/docs/llms-full.txt).
- The documentation website is performing better now due to dependency improvements.
---
## February 2025
In February 2025, the Pdftools documentation included the following updates:
## Added
- All release notes, such as the [Pdftools SDK](../../pdf-tools-sdk/release-notes/#pdftools-sdk), [Toolbox add-on](../../pdf-tools-sdk/release-notes/#toolbox-add-on), [Conversion Service](../../conversion-service/release-notes/), and the PDF Viewer SDK (both [version 5](../../pdf-web-viewer/release-notes/) and [version 4](../../pdf-web-viewer/4/release-notes/)), received dates for each release. As a result, it is now clear when a release occurred from the release notes.
- Added new Python API references for the [Pdftools SDK](https://api-reference.pdf-tools.com/pdfsdk/1.8/pydocs/index.html) and the [Toolbox add-on](https://api-reference.pdf-tools.com/pdfsdkxt/1.5/pydocs/index.html).
- This documentation now mentions that the Conversion Service supports Office 2024 (64-bit) for Microsoft Office file conversion. For more information, review [Convert Microsoft Office files](/docs/conversion-service/configure/office-conversion/) guide.
- The [Update Conversion Service on Windows Server](../../conversion-service/update/windows-server/) and [Update Conversion Service in Docker](../../conversion-service/update/docker/) guides received major updates in their structure and delivery.
- [Conversion Service on Windows Server](/docs/conversion-service/getting-started/windows-server/) getting started guide and [Conversion Service in Docker getting started](/docs/conversion-service/getting-started/docker/) guide were updated to properly display instructions for the new [Pdftools Portal](https://portal.pdf-tools.com/), including the details about the new trial license key use. Both guides also better explain what applications are installed using the Windows Server and Windows client installers.
- PDF Viewer SDK versions [5.2.0](../../pdf-web-viewer/release-notes/#version-520) and [5.3.0](../../pdf-web-viewer/release-notes/#version-530) release notes were added to the PDF Viewer SDK release notes.
## Fixed
- All [Pdftools SDK getting started guides](../../pdf-tools-sdk/getting-started/pdftools-sdk/) received numerous fixes and updates. The initialization step was clearly marked as optional in all these guides. The initialization is necessary for commercial use, but optional for evaluating users. If you need to try the Pdftools SDK, you can do it without the initialization with watermarked results.
- Updated commands in the [Full offline mode](/docs/licenses/configure/offline-licensing-gateway-service/) licensing documentation.
- Numerous typos were corrected, many broken links were fixed, and many more small updates were made in all areas of this documentation.
---
## January 2025
In January 2025, the Pdftools documentation included the following updates:
## Added
- The Pdftools SDK documentation was updated after the 1.8.0 SDK release. Documentation for the version 1.5.0 was removed as only three versions of the Pdftools SDK docs are kept on the documentation website for simplicity. For more information, review Pdftools SDK [1.8.0 release notes](../../pdf-tools-sdk/release-notes/#version-180).
- The Toolbox add-on received an update to version 1.5.0. Review the [release notes](../../pdf-tools-sdk/release-notes/#version-150-1) for more details.
- LTS version of the PDF Viewer SDK received a 4.3.4 patch. Review the [4.3.4 release notes](../../pdf-web-viewer/4/release-notes/#434) for the patch information.
- Added a new article explaining SSL configuration details for the Licesing Gateway Service (LGS). Review [Configure SSL](../../licenses/configure/ssl-licensing-gateway-service) for more details.
- The **SSL certificate problem: unable to get local issuer certificate** issue is now documented under licensing [Frequently asked questions](../../licenses/#frequently-asked-questions).
- The Pdftools SDK Shell Tool documentation now includes the [Pdftools SDK Shell Tool 1.6.0](/docs/pdf-tools-sdk/release-notes/#version-160-2) release notes.
## Changed
- Link to our Discord channel was removed. If you need our support, please reach out through the [support page](../../support/).
## Fixed
- Pdftools SDK [Python getting started](../../pdf-tools-sdk/getting-started/pdftools-sdk/pdftools-sdk-python/) received a major update and fixes.
- The [Toolbox add-on getting started guides](../../pdf-tools-sdk/getting-started/toolbox/) also received minor fixes and updates.
- [PDF Viewer SDK standard implementation](../../pdf-web-viewer/standard-implementation/) documentation received an update with fixes to the style, delivery, and code snippet improvements. For more information, review:
- [View a PDF](../../pdf-web-viewer/standard-implementation/view-pdf/)
- [Customize the PDF Viewer SDK](../../pdf-web-viewer/standard-implementation/customize-viewer/)
---
## July 2025
In July 2025, the Pdftools documentation included the following updates:
## Added
- Release notes for the Pdftools SDK [version 1.13.0](/docs/pdf-tools-sdk/release-notes/#version-1130), Toolbox add-on [version 1.9.0](/docs/pdf-tools-sdk/release-notes/#version-190-1), and the Pdftools SDK Shell Tool [version 1.9.0](/docs/pdf-tools-sdk/release-notes/#version-190-1). The [Pdftools SDK](/docs/pdf-tools-sdk/) documentation pages include updated [API reference](/docs/pdf-tools-sdk/api-references/) links and [code samples](/docs/pdf-tools-sdk/code-samples/).
- Pdftools SDK documentation now includes the [Accessibility](/docs/pdf-tools-sdk/toolbox/accessibility/) category with three new guides:
- [Create an accessible PDF from scratch](/docs/pdf-tools-sdk/toolbox/accessibility/create-accessible-pdf/)
- [Add logical structure to an existing PDF](/docs/pdf-tools-sdk/toolbox/accessibility/add-logical-structure-to-existing-pdf/)
- [Read PDF logical structure](/docs/pdf-tools-sdk/toolbox/accessibility/read-logical-structure/)
- Initial [version 1.0.0 of the Pdftools OCR Service](/docs/ocr-service/) documentation with getting started page, configuration pages, release notes, and references.
- Conversion Service [version 6.4.0](/docs/conversion-service/release-notes/#640) release notes.
- Conversion Service documentation now includes an MS Office conversion [Troubleshooting](/docs/conversion-service/configure/office-troubleshooting/) page, with a [Manual investigation](/docs/conversion-service/configure/office-troubleshooting/#manual-investigation) section.
- Patch release notes [5.7.6](/docs/conversion-service/release-notes/#576) for the LTS version of the Conversion Service.
- PDF Viewer SDK [version 5.7.0](/docs/pdf-web-viewer/release-notes/#version-570) release notes with updated [API references](/docs/pdf-web-viewer/category/api-references/).
- Updated section [Offline license activation](/docs/licenses/configure/offline-licensing-gateway-service/#offline-license-configuration) in the Licensing Gateway Service (LGS) documentation to provide steps to [Activate license key in the Pdftools Portal](/docs/licenses/configure/offline-licensing-gateway-service/#activate-license-key-in-the-pdftools-portal) or [Deactivate license key in the Pdftools Portal](/docs/licenses/configure/offline-licensing-gateway-service/#deactivate-license-key-in-the-pdftools-portal).
## Changed
- The [Pdftools SDK Python getting started guide](/docs/pdf-tools-sdk/getting-started/pdftools-sdk/pdftools-sdk-python/) and the [Toolbox add-on Python getting started guide](/docs/pdf-tools-sdk/getting-started/toolbox/toolbox-python/) now include shorter `pip install` commands.
## Fixed
- A script download link works correctly on the [Migration script](/docs/pdf-toolbox-sdk/migration-guide/use-migration-script/) page in the legacy PDF Toolbox SDK documentation.
- Improved typography of displayed documentation.
- Fixed numerous typos, links, and other small improvements in many pages of this documentation.
---
## June 2025
In June 2025, the Pdftools documentation included the following updates:
## Added
- The documentation now includes release notes for the Pdftools SDK [version 1.12.0](/docs/pdf-tools-sdk/release-notes/#version-1120), updated API reference links, and code samples.
- Pdftools SDK Shell Tool release notes [version 1.8.0](/docs/pdf-tools-sdk/release-notes/#version-180-2).
- The Toolbox add-on received release notes for [version 1.8.0](/docs/pdf-tools-sdk/release-notes/#version-180-1) with updated API reference links and code samples.
- Pdftools SDK licensing docs now include the [Configure proxy](/docs/licenses/products/pdf-tools-sdk-license/#configure-proxy) and [Operations](/docs/licenses/products/pdf-tools-sdk-license/#operations) sections.
- Conversion Service release notes for [version 6.3.0](/docs/conversion-service/release-notes/#630) have been added. The following documents received an update:
- [Configure stamps and annotations](/docs/conversion-service/configure/configure-stamping/) documentation.
- [Stamp and annotation](/docs/conversion-service/workflows/stamping/) workflow documentation.
- Minor updates in the [Cryptographic providers](/docs/conversion-service/configure/configure-signature/set-up-signature/).
- Added two new troubleshooting sections in the Conversion Service Microsoft Office conversion documentation:
- [The server process could not be started because the configured identity is incorrect (COM exception 0x8000401a)](/docs/conversion-service/configure/office-troubleshooting/#the-server-process-could-not-be-started-because-the-configured-identity-is-incorrect-com-exception-0x8000401a).
- [Access is denied (COM exception 0x80070005)](/docs/conversion-service/configure/office-troubleshooting/#access-is-denied-com-exception-0x80070005)
- Conversion Service OCR documentation now includes online ABBYY license type information in the [Activate ABBYY license](/docs/conversion-service/configure/ocr/configure-ocr-your-own-license-key/#activate-abbyy-license) section and related sub-sections.
- Licensing documentation now mentions that you can configure Conversion Service to be used in the [containerized mode](/docs/licenses/configure/docker-licensing-gateway-service/) and links you to the Conversion Service [Configure containers using Docker Compose](/docs/conversion-service/configure/configure-docker-container/#configure-containers-using-docker-compose) documentation section, where you can find an example of Docker Compose YAML file that enables LGS containerized mode configuration.
- The Conversion Service [Windows Server](/docs/conversion-service/getting-started/windows-server/) and [Docker](/docs/conversion-service/getting-started/docker/) getting started guides now include an improved description explaining that you need to use fonts installed on your processing machine.
- PDF Viewer SDK documentation received version [5.6.0 release notes](/docs/pdf-web-viewer/release-notes/#version-560) and updated [API references](/docs/pdf-web-viewer/category/api-references/).
- Legacy Toolbox SDK received patches [version 4.4.10](/docs/pdf-toolbox-sdk/release-notes/#version-4410) and [version 4.4.11](/docs/pdf-toolbox-sdk/release-notes/#version-4411).
- Enabled search through tags within documentation product areas. Tags will directly lead you to the referenced page. You can find the tags at the end of each page and list all tags within a product area. Tags are separate for each documentation area. The following list includes three main documentation product areas where the tags were added:
- [Pdftools SDK tags](/docs/pdf-tools-sdk/tags/)
- [Conversion Service tags](/docs/conversion-service/tags/)
- [PDF Viewer SDK tags](/docs/pdf-web-viewer/tags/)
- Example: Try clicking on a tag like [Merge and split PDFs](/docs/pdf-tools-sdk/tags/merge-and-split-pd-fs/) at the end of a page to jump directly to related documents.
- [LLMs.txt](https://www.pdf-tools.com/docs/llms.txt) and [LLMs-full.txt](https://www.pdf-tools.com/docs/llms-full.txt) were added to provide LLMs with an easily parsable text format.
## Changed
- In the Conversion Service documentation:
- [Conversion Service licensing](/docs/licenses/products/conversion-service-license/) documentation now mentions **page credits** instead of **credits**. This change can better explain the usage-based license key functionality (instead of **X credits per page**, we now state **X page credits**).
- The **Stamping** workflow was renamed to [Stamp and annotation](/docs/conversion-service/workflows/stamping/).
- The **Warnings** configuration section was renamed to **Events**.
- The **Document Optimization** processing step (included in all PDF/A workflows) was renamed to **Compression and Optimization**.
- The **What's new** tag was removed from the What's new documentation area.
## Fixed
- Links to the new [Pdftools Portal](https://portal.pdf-tools.com/) have been updated. Despite the new [Pdftools Portal](https://portal.pdf-tools.com/), some products and license keys are only accessible in the legacy portal. Select which customer portal to access on the [Select your login](https://portal.pdf-tools.com/intermediate) page.
- All pages in the Conversion Service [Workflows](/docs/conversion-service/workflows/) documentation category received correct level headers, typo fixes, screenshot size adjustments, and other updates.
---
## March 2025
In March 2025, the Pdftools documentation included the following updates:
## Added
- Pdftools SDK documentation now includes the [Embed e-invoice guide](/docs/pdf-tools-sdk/e-invoice/) and a related code sample, [Create a ZUGFeRD invoice](/docs/pdf-tools-sdk/code-samples/pdftools-sdk-samples/#create-a-zugferd-invoice). You can use the provided information and code sample to create e-invoices in both ZUGFeRD and Factur-X formats.
- Added Pdftools SDK [version 1.9.0](/docs/pdf-tools-sdk/release-notes/#version-190) release notes and Toolbox add-on [version 1.6.0](/docs/pdf-tools-sdk/release-notes/#version-160-1) release notes.
- Conversion Service release notes for [version 6.0.0](/docs/conversion-service/release-notes/#600) were added. Two significant documentation updates are connected to this version:
- Conversion Service documentation now includes the [Conversion Service on OpenShift](/docs/conversion-service/configure/configure-openshift/) guide.
- The beta version of the Configurator Web was released with an initial minimal documentation section, [Configure profiles using Configurator Web](/docs/conversion-service/configure/configure-profiles-docker/#configure-profiles-using-configurator-web).
- The Conversion Service log files are now explained in the [Conversion Service on Windows Server](/docs/conversion-service/getting-started/windows-server/) getting started guide.
- PDF Viewer SDK [version 5.4.0](/docs/pdf-web-viewer/release-notes/#version-540) release notes. The PDF Viewer SDK [API references](/docs/pdf-web-viewer/category/api-references/) were also updated.
- Added [PDF Toolbox SDK 4.4.9](/docs/pdf-toolbox-sdk/release-notes/#version-449) patch release notes. Note that PDF Toolbox SDK features and functionality are now included in the Toolbox add-on for Pdftools SDK.
- The Algolia Search widget in this documentation now includes an option to use your search input in the kapa.ai widget. When you search for a term in the Algolia Search widget, you can click **Can you tell me about**, which is marked as the first search result, to get an answer from kapa.ai, an LLM trained specifically on the data from this documentation website.
- The documentation website now includes lightboxes for images. When you click an image, it is enlarged to display more detail. The lightbox can be closed by pressing any key on your keyboard or scrolling.
## Changed
- The **Download** button included in the code samples was moved below the programming language selection to clarify that these code samples, such as [Pdftools SDK code samples](/docs/pdf-tools-sdk/code-samples/pdftools-sdk-samples/) or [Toolbox add-on code samples](/docs/pdf-tools-sdk/code-samples/pdftools-sdk-toolbox-samples/), must be downloaded so you can use them.
- The optional [Install and configure additional clients](/docs/conversion-service/getting-started/windows-server/#optional-install-and-configure-additional-clients) section in the Conversion Service getting started guide was moved within the guide.
- If you are installing the Conversion Service on regular Windows (instead of Windows Server), you no longer need the `msiexec /i ConversionService-VERSION_NUMBER.msi PDF_TOOLS_DISABLE_OS_CHECK=1` command to enable the installation. This step was removed from the [Conversion Service in Docker](/docs/conversion-service/getting-started/docker/) getting started guide.
- The PDF Toolbox SDK version 3.11 and the Conversion Service version 3.11 were removed from the [Supported LTS product releases](/docs/support/release-management/#supported-lts-product-releases) table in [Release management](/docs/support/release-management/) documentation. The official LTS support for both product versions ended in 2024. PDF Viewer SDK version 4.3 was added as one of the LTS versions.
## Fixed
- Fixed documentation website caching issues and related broken links.
- Simplified headers, labels, and clarified placeholders in [Conversion Service](/docs/conversion-service/) documentation.
- Removed repeated word **Configure** in nearly every Conversion Service [Configure](/docs/conversion-service/configure/) documentation section item.
- Added a note that the Licensing Gateway Service is already installed with the Conversion Service on Windows Server. Installing LGS a second time may render the Conversion Service unusable. The note also clarifies that full offline mode functionality is unavailable in the Conversion Service. Review [Full offline mode](/docs/licenses/configure/offline-licensing-gateway-service/) for more information.
---
## May 2025
In May 2025, the Pdftools documentation included the following updates:
## Added
- Pdftools SDK code samples now include links to Jupyter notebooks labeled as **Open in colab** buttons. Review the following code samples:
- [Pdftools SDK code samples](/docs/pdf-tools-sdk/code-samples/pdftools-sdk-samples/)
- [Toolbox add-on code samples](/docs/pdf-tools-sdk/code-samples/pdftools-sdk-toolbox-samples/)
- Release notes for the Pdftools SDK versions [1.10.0](/docs/pdf-tools-sdk/release-notes/#version-1100), [1.11.0](/docs/pdf-tools-sdk/release-notes/#version-1110), and patch [1.11.1](/docs/pdf-tools-sdk/release-notes/#version-1111) have been added to the documentation with updated API reference links and code samples.
- The Toolbox add-on received release notes for [version 1.7](/docs/pdf-tools-sdk/release-notes/#version-170-1) and patch [version 1.7.1](/docs/pdf-tools-sdk/release-notes/#version-171).
- The Conversion Service documentation now includes release notes for [version 6.2.0](/docs/conversion-service/release-notes/#620). This version came with the following documentation updates:
- The [Licensing Gateway Service (LGS) full offline mode](/docs/licenses/configure/offline-licensing-gateway-service/) is now enabled for the Conversion Service.
- The [Accessibility workflow](/docs/conversion-service/workflows/accessibility/) initial documentation has been published.
- The [Licensing credit count](/docs/licenses/products/pdf-tools-sdk-license/#licensing-credit-count) and [Calculating credits](/docs/licenses/products/pdf-tools-sdk-license/#calculating-credits) sections have been added to the Pdftools SDK licensing documentation.
- The **What's new** documentation category you are reading now has been created to inform you about updates in the Pdftools documentation. The entries in this category have been added retrospectively since the beginning of the year 2025.
## Changed
- The `latest` tag was removed from the Conversion Service Docker documentation. For more information, review [version 6.2.0](/docs/conversion-service/release-notes/#620) release notes.
- The legacy [Customer portal](https://my.pdf-tools.com/en/mypdftools/licenses-kits/) URL was changed from `https://www.pdf-tools.com/en/mypdftools/licenses-kits/` to `https://my.pdf-tools.com/en/mypdftools/licenses-kits/`. Note that there is now a new customer portal. However, some products and license keys are only accessible in the legacy portal. You can select which customer portal to access on the [Select your login](https://portal.pdf-tools.com/intermediate) page.
## Fixed
- The [Convert Microsoft Office files](/docs/conversion-service/configure/office-conversion/) page in the Conversion Service documentation has been updated. You can now directly link to all subsections previously hidden within tabs. Additionally, wording, formatting, and various minor issues have been addressed.
- Minor fixes have been applied to the [Conversion Service](/docs/conversion-service/) documentation landing page, [Conversion Service in Docker](/docs/conversion-service/getting-started/docker/) guide, PDF Viewer SDK [Custom implementation guides](/docs/pdf-web-viewer/guides/), and the [Full offline mode](/docs/licenses/configure/offline-licensing-gateway-service/) licensing documentation.
- General deployment processes for documentation have been enhanced to ensure greater stability and accessibility.
---
## October 2025
In October 2025, the Pdftools documentation included the following updates:
## Added
- Added the Pdftools SDK documentation release notes for [version 1.14.0](/docs/pdf-tools-sdk/release-notes/#version-1140) and updated links to [API references](/docs/pdf-tools-sdk/api-references/).
- Added section [Adding custom font lookup paths](/docs/pdf-tools-sdk/api-references/technical-notes/general-notes/#adding-custom-font-lookup-paths) to the Pdftools SDK technical notes.
- Improved and optimized performance of the [Pdftools SDK](/docs/pdf-tools-sdk/code-samples/pdftools-sdk-samples/) and the [Toolbox add-on](/docs/pdf-tools-sdk/code-samples/pdftools-sdk-toolbox-samples/) code sample pages.
- Added the Toolbox add-on documentation release notes for [version 1.11.0](/docs/pdf-tools-sdk/release-notes/#version-1110-1) and updated links to [API references](/docs/pdf-tools-sdk/api-references/).
- Added release notes for the Pdftools SDK Shell Tool [version 1.10.0](/docs/pdf-tools-sdk/release-notes/#version-1100-2).
- Added release notes for the Conversion Service [version 6.6.0](/docs/conversion-service/release-notes/#660).
This Conversion Service release also includes documentation related to newly added Gmail connectors with the following sections and subsections:
- [Watched Mailbox (Gmail)](/docs/conversion-service/integrate/connectors/email-connectors/#watched-mailbox-gmail)
- [Watched Mailbox (Gmail App Passwords)](/docs/conversion-service/integrate/connectors/email-connectors/#watched-mailbox-gmail-app-passwords)
- [Watched Mailbox (Gmail OAuth 2.0)](/docs/conversion-service/integrate/connectors/email-connectors/#watched-mailbox-gmail-oauth-20)
- [Output Mailbox (Gmail)](/docs/conversion-service/integrate/connectors/email-connectors/#output-mailbox-gmail)
- [Output Mailbox (Gmail App Passwords)](/docs/conversion-service/integrate/connectors/email-connectors/#output-mailbox-gmail-app-passwords)
- [Output Mailbox (Gmail OAuth 2.0)](/docs/conversion-service/integrate/connectors/email-connectors/#output-mailbox-gmail-oauth-20)
- [Send Email (Gmail)](/docs/conversion-service/integrate/connectors/email-connectors/#send-email-gmail)
- [Send Email (Gmail App Passwords)](/docs/conversion-service/integrate/connectors/email-connectors/#send-email-gmail-app-passwords)
- [Send Email (Gmail OAuth 2.0)](/docs/conversion-service/integrate/connectors/email-connectors/#send-email-gmail-oauth-20)
- PDF Viewer SDK release notes and updated API references for versions:
- [5.10.0](/docs/pdf-web-viewer/release-notes/#version-5100)
- [5.9.0](/docs/pdf-web-viewer/release-notes/#version-590)
- Expanded [Pdftools OCR Service licensing](/docs/licenses/products/ocr-service-license/) documentation with more information about offline license key usage, and a precise procedure and prerequisites.
- This documentation website now offers an enhanced sidebar contrast and improved visibility for currently open pages.
## Fixed
- Updated [PDF Viewer SDK architecture](/docs/pdf-web-viewer/api-references/) documentation.
- Removed tabs with nested sub-headings from the Pdftools SDK [General technical notes](/docs/pdf-tools-sdk/api-references/technical-notes/general-notes/) for better clarity.
- Expanded [Excel conversion fails with a “Generic” error (COM exception 0x800a03ec)](/docs/conversion-service/configure/office-troubleshooting/#excel-conversion-fails-with-a-generic-error-com-exception-0x800a03ec) section in the [Troubleshooting Microsoft Office file conversion documentation](/docs/conversion-service/configure/office-troubleshooting/).
- When you switch pages on this documentation website, the displayed fonts no longer switch between fonts for a split second.
- Fixed numerous typos and other minor issues in many documentation pages.
---
## September 2025
In September 2025, the Pdftools documentation included the following updates:
## Added
- Restructured and expanded the Pdftools OCR Service documentation:
- Consolidated [Get started with OCR in the Conversion Service](/docs/ocr-service/getting-started/) guide to provide information from installation to initial configuration.
- New page [Pdftools OCR Service licensing](/docs/licenses/products/ocr-service-license/) with [Configuration in connected mode and full offline mode](/docs/licenses/products/ocr-service-license/#configuration-in-connected-mode-and-full-offline-mode) section. The page includes details on how to configure the Pdftools OCR Service in both Connected mode and Full offline mode. Additionally, the Pdftools OCR Service licensing includes additional setup steps that you must follow for the OCR service after configuring the [Pdftools Licensing Service](/docs/licenses/configure/) in Full Offline mode or Connected mode.
- New page [Work with profiles](/docs/ocr-service/guides/profiles/).
- Improved directory structure and information architecture, more comprehensive URLs, shortened titles and sidebar labels, and fixes in [References](/docs/ocr-service/references/).
- The Pdftools SDK released a patch version [1.13.1](/docs/pdf-tools-sdk/release-notes/#version-1131).
- The Toolbox add-on SDK released a minor version [1.10.0](/docs/pdf-tools-sdk/release-notes/#version-1100-1).
- The Pdftools SDK Shell Tool released a patch version [1.9.1](/docs/pdf-tools-sdk/release-notes/#version-191-1).
- The Conversion Service released the following versions:
- Minor version [6.5.0](/docs/conversion-service/release-notes/#650).
- Patch version [6.4.2](/docs/conversion-service/release-notes/#642).
- The Conversion Service licensing includes the following new sections:
- [Full offline mode license activation](/docs/licenses/products/conversion-service-license/#full-offline-mode-license-activation)
- [Extend Full offline mode license](/docs/licenses/products/conversion-service-license/#extend-full-offline-mode-license)
- [Remove Full offline mode license](/docs/licenses/products/conversion-service-license/#remove-full-offline-mode-license)
- The PDF Viewer SDK released minor version [5.8.0](/docs/pdf-web-viewer/release-notes/#version-580) with updated [API references](/docs/pdf-web-viewer/category/api-references/).
- Added section [LGS supported operating systems and environments](/docs/licenses/configure/#lgs-supported-operating-systems-and-environments).
- [Full offline mode](/docs/licenses/configure/offline-licensing-gateway-service/) page includes a note about the limitations of full offline mode, and the tabs that display Linux Snap package installation mention that the Licensing Gateway Service requires **glibc 2.34+**.
- The [Pdftools SDK](/docs/pdf-tools-sdk/code-samples/pdftools-sdk-samples/) and [Toolbox add-on](/docs/pdf-tools-sdk/code-samples/pdftools-sdk-toolbox-samples/) **code samples** received the following updates:
- Added the right panel table of contents (TOC) to provide an overview of categories within the samples.
- Fixed code highlighting inconsistency, dark and light mode switching.
- The code samples now use the correct code theme in both light and dark modes.
- Responsive TOC for smaller screens added on top of the pages as a clickable **On this page** modal.
## Changed
- Removed references to [languages](/docs/ocr-service/references/ocr-languages/) that the Pdftools OCR Service doesn't support. These languages include Arabic, Burmese, Chinese (Simplified and Traditional), Farsi, Hebrew, Japanese, Korean, Latvian (written in Gothic script), Old English, Old French, Old German, Old Italian, Old Slavonic, Old Spanish, Pashto, Thai, Urdu, Vietnamese, and Yiddish.
To request support for any of these languages, let us know using the [contact page](https://www.pdf-tools.com/contact/).
## Fixed
- Typo fixes, delivery, and style improvements in all pages within the [Workflows](/docs/conversion-service/workflows/) category of the Conversion Service docs.
- Updated the Algolia Search integration to the latest version and reimplemented its custom features. To open the search modal, use Ctrl + k on Linux or Windows, and ⌘ + k on macOS.
Example custom search feature: When you search within a product area, such as [Pdftools SDK](/docs/pdf-tools-sdk/), [Conversion Service](/docs/conversion-service/), or [What's new](/docs/whats-new/), the search displays results from that product area first.
- Updated code sample downloadable links in the [Guides](/docs/pdf-tools-sdk/category/guides/) category with links to newly added languages for each use case, making them more prominently visible. For example, the [Archive a PDF document to PDF/A](/docs/pdf-tools-sdk/archive/archive-pdf-pdfa/) guide includes a visible admonition stating **Quick start with a code sample** with bold links to each sample, including C, Python, and Visual Basic.
- Fixed the Conversion Service version selection menu from appearing on the What's new page.
- The [llms.txt](https://www.pdf-tools.com/docs/llms.txt) and [llms-full.txt](https://www.pdf-tools.com/docs/llms-full.txt) autogeneration issues.
---
## PDF Viewer SDK(Version-4)
PDF Viewer SDK is a compact, high performance viewer for PDF files, offering a multitude of navigational and display options. It lets you add PDF viewing and annotating functionality to your application. PDF Viewer SDK runs in a web browser, or in a JavaScript, WebAssembly container.
## Supported input and output file formats
- PDF 1.x (PDF 1.0, …, PDF 1.7)
- PDF 2.0
- PDF/A-1, PDF/A-2, PDF/A-3
- FDF
## Conformance
- ISO 32000-1 (PDF 1.7)
- ISO 32000-2 (PDF 2.0)
- ISO 19005-1 (PDF/A-1)
- ISO 19005-2 (PDF/A-2)
- ISO 19005-3 (PDF/A-3)
## Supported browsers
All the following version numbers represent the minimal supported version. The plus **+** after the version number signifies that this or a higher version of a browser is supported.
- Chrome 63+
- Firefox 55+
- Edge 41+
- Safari 11.03+
## Features
- Responsive UI with no external dependencies and support for mobile devices.
- Navigate manually (user action) or programmatically through a document.
- Select among six different layout modes for one-page and facing-pages viewing.
- Select different fit modes: actual size, fit to width, fit to page.
- Pre-configure allowed zoom levels.
- Rotate the page display.
- Search the document for a given text.
- User interface in is pre-configured in languages such as English, German, French, Italian and you can also use a custom translation.
- Display thumbnails and use them for navigation.
- Show the document outline (bookmarks) and use it for navigation.
- Show annotations and use them for navigation.
- Annotations and form fields can be filtered before saving to PDF or Forms Data Format (FDF).
- Fill out form fields (check boxes, radio buttons, list boxes, drop-down lists, text fields).
- Create, edit, and delete annotations.
- Sticky-note annotations.
- Text highlight annotations (highlight, strike out, underline, squiggly).
- Text annotations.
- Free-hand drawings.
- Eraser tool for deleting individual lines in free-hand drawings.
- Predefined text stamp annotations (for example: draft, approved).
- Use pages of a PDF as stamp annotations.
- Use an image as stamp annotation.
- Rectangle and ellipse annotations.
- Touch handling for mobile devices.
- Enter password to open encrypted PDF documents.
- Read document from file, URL or blob.
- Support loading and storing annotations in the FDF.
- Prevent the modification and deletion of all annotations except for a configured author.
- Viewing-only mode with annotation editing and filling disabled.
- Print a document.
- Easy evaluation without the necessity of a license key.
- Available on [npmjs](https://www.npmjs.com/package/@pdf-tools/four-heights-pdf-web-viewer).
:::note
Section **How to Migrate from 3-Heights®** is only available in [PDF Viewer legacy documentation](https://www.pdf-tools.com/public/downloads/manuals/PdfWebViewer.pdf) and is not yet migrated to this documentation.
:::
---
## Getting started with the PDF Viewer SDK(Version-4)
Get started with a compact, high-performance PDF document viewer by following this guide.
## Run a sample
Learn how to run the PDF Viewer SDK sample:
1. Download or clone the [sample repository](https://github.com/pdf-tools/pdf-web-viewer-samples/tree/4.3.4).
1. From the root of the repository, navigate to a sample at:
```
examples/vanilla-typescript/view-pdf
```
1. Install dependencies:
```
npm install
```
1. Build the project:
```
npm run build
```
1. Run the server:
```
npm run dev
```
1. Open [`http://localhost:4567/`](http://localhost:4567/) in your browser.
:::tip samples
Run other samples in the same way. Review the `/examples` directory for more samples in the downloaded or cloned [sample repository](https://github.com/pdf-tools/pdf-web-viewer-samples/tree/4.3.4).
:::
## Integrate the SDK into your application
The following sections guide you through the installations, deployment, and integration of the PDF Viewer SDK.
### Install and deploy
:::tip Prerequisite
The npm package complies with Node.js version 14 or higher.
:::
The PDF Viewer SDK is distributed as an npm package or as a ZIP archive containing an example JavaScript web application.
The npm package is provided through [npmjs.com](https://www.npmjs.com/package/@pdf-tools/four-heights-pdf-web-viewer) and can be installed with:
```bash
npm i @pdf-tools/four-heights-pdf-web-viewer --save
```
The package contains the following directories:
| Directory | Description |
| -------------- | ------------------------------------------------------ |
| `css` | The compiled CSS |
| `docs` | Documentation |
| `es6` | Source code |
| `pdfwebviewer` | Static assets. See [Static asset management](#static-asset-management). |
| `scss` | Sass CSS source files |
| `umd` | Main JavaScript and source code mappings |
| `wasm` | WebAssembly and data files |
| `LICENSE.md` | General licensing agreement |
| `README.md` | Quickstart read-me file |
You can also obtain the PDF Viewer SDK from the Pdftools [My PDF Tools Portal](https://my.pdf-tools.com/en/mypdftools/licenses-kits/) as a self-contained example JavaScript web application in the form of a ZIP archive with the following content:
| Subdirectory | Description |
| --------------------- | ------------------------------------------------------ |
| `doc` | License terms and documentation |
| `webapp` | minimal.html: A minimal HTML with the default WebViewerOptionsindex.html: An example HTML with a wide range of WebViewerOptions.htaccess, web.config: Server configuration files for Apache and Windows IIS |
| `webapp/pdfwebviewer` | Includes static assets. Review Static asset management for more information.Development source code mapping files: pdf-web-viewer.development.jspdf-web-viewer.development.map.js |
Review [WebViewerOptions](./reference/README.mdx#webvieweroptions) reference documentation.
### Static asset management
It's necessary to serve the static assets for the PDF Viewer SDK to function. Among the static assets, you can find predefined language files with translations that are ready for use. These languages include English, German, French, and Italian. You can exclude and add your own custom translation files. The static assets are contained in the package subdirectory `pdfwebviewer`:
- Main JavaScript file: `pdf-web-viewer.min.js`
- Compiled CSS: `pdf-web-viewer.css`
- WebAssembly, associated JavaScript, and data files:
- `PdfViewing.data`
- `PdfViewing_Main.js`, `PdfViewing_Main.wasm`
- `PdfViewing_Worker.js`, `PdfViewing_Worker.wasm`
- Translation files:
- `translations.en.json`
- `translations.de.json`
- `translations.fr.json`
- `translations.it.json`
After installing or updating the PDF Viewer SDK:
1. Copy the static assets from the `pdfwebviewer` subdirectory to the **base URL** location.
:::note
You can exclude unused translation files and custom translation files can be added. Review [Custom translations](./guides/README.mdx#custom-translations) for more information.
:::
#### Base URL
Serve the static assets with the targeted application from a **base URL**. The base URL is configured by setting the JavaScript property `window.PDFTOOLS_FOURHEIGHTS_PDFVIEWING_BASEURL`. The base URL can be a path relative to the main HTML file or an absolute path. For example:
- `./path/to/pdfwebviewer`: File path relative to the `index.html`.
- `/file/viewer/pdfwebviewer`: Absolute file path.
- `file:///e:/electron-app/pdfwebviewer`: Absolute file path.
The base URL must be set prior to loading the PDF Viewer SDK. For example, in the `head` element of the main HTML file as:
```html
```
#### Manual copying
Not recommended: It is possible to manually copy the asset files. However, if you need to copy the files again before the build, you can forget to do so. For example, when using the npm package, `PDFTOOLS_FOURHEIGHTS_PDFVIEWING_BASEURL` is defined as `./pdfwebviewer/`, and your main directory for static assets is `static`.
```bash
cp -R ./node_modules/@pdf-tools/four-heights-pdf-web-viewer/pdfwebviewer ./static
```
If you need to copy specific asset files, use tools such as the `CopyWebpackPlugin` instead of manual copying. For more information, review the following section [Automated copying](#automated-copying).
#### Automated copying
When using the npm package, it is recommended to use a bundler which copies the static assets during the build process. See the following examples:
For Webpack:
```javascript
const path = require('path')
const CopyWebpackPlugin = require('copy-webpack-plugin')
const pdfwebviewerDir = path.join(
path.dirname(require.resolve('@pdf-tools/four-heights-pdf-web-viewer')),
'../pdfwebviewer'
)
module.exports = {
...
plugins: [
new CopyWebpackPlugin({
patterns: [
{
from: '**/*',
to: 'pdfwebviewer', // Match with PDFTOOLS_FOURHEIGHTS_PDFVIEWING_BASEURL
context: pdfwebviewerDir,
}
],
}),
],
}
```
For Angular in `angular.json`:
```json
"projects": {
"angular": {
"architect": {
"build": {
"options": {
"assets": [
{
"glob": "**/*",
"input":
"./node_modules/@pdf-tools/four-heights-pdf-web-viewer/pdfwebviewer",
"output":
"./pdfwebviewer" // Match with PDFTOOLS_FOURHEIGHTS_PDFVIEWING_BASEURL
},
],
},
},
},
},
}
```
### Basic usage
A simple web application that uses the PDF Viewer SDK with the default [WebViewerOptions](./reference/README.mdx#webvieweroptions) is implemented as follows.
In the `index.html`:
```html
PDF Web Viewer
{/* HTM element containing the PdfWebViewer. */}
```
:::info License key
In the `index.js` set a valid license key in the `const license = ''`. Without a valid license key the output files are watermarked. Get in touch with the Pdftools sales team through the [Contact page](https://www.pdf-tools.com/contact/) to get a full license.
:::
In the `index.js`:
```javascript
import { PdfWebViewer } from '@pdf-tools/four-heights-pdf-web-viewer'
const element = document.getElementById('pdfviewer')
const license = ''
// use default options
const options = {}
const pdfViewer = new PdfWebViewer(element, license, options)
```
### Server configuration
It is necessary to configure the correct content types for the `*.wasm` and the `*.data` files.
#### Windows IIS
The content types can be configured for a Windows Internet Information Services (IIS) web server by means of the following `web.config` file:
```xml
```
:::tip
In the `web.config` file, you can also configure caching settings for the PDF Viewer SDK static assets.
:::
Apart from `web.config` there is also `%SYSTEMROOT%\System32\inetsrv\Config\applicationHost.config`. Depending on the IIS version, this file already contains some of the MIME type mapping entries. In this case, remove the duplicate entries from `web.config`.
#### Apache
The content types can be configured for an Apache web server by means of the following`.htaccess` file:
```
AddType application/octet-stream ".mem"
AddType application/octet-stream ".data"
AddType application/wasm ".wasm"
```
In this file, you can also configure caching settings for the PDF Viewer SDK static assets.
### License keys
The PDF Viewer SDK can without a license key with watermarked results. To remove the watermark, request an evaluation or full license key from the Pdftools sales team through the [Contact page](https://www.pdf-tools.com/contact/).
:::tip Use the license key
To enter the license key, pass the license key as a second argument of the `PdfWebViewer` constructor (in the `const license = ''`). Review [Basic usage](#basic-usage) for detailed information.
:::
:::info Troubleshooting
For troubleshooting of issues related to the license key, review [PDF Viewer license](/docs/licenses/products/pdf-web-viewer-license/) documentation.
:::
---
## Technical notes(Guides)
Learn how to configure range requests, find and configure keyboard shortcuts, find out about custom translations, keyboard shortcuts, and learn how to add custom buttons.
## Range requests
:::tip
Using range requests can considerably shorten initial load times for large PDFs.
:::
When opening a PDF from a URL using the `openFile` method, the PDF Viewer SDK can use **HTTP range requests** to load only those parts of the PDF needed for the current display.
Each range request that PDF Viewer SDK makes has an approximate size 130 kB.
Ensure that the server accesses the PDF in a random-access way. Otherwise, each range request can force the server to reload the entire file.
## Viewing-only edition
The PDF Viewer SDK in a **viewing-only** edition has the following limitations:
- Saving the PDF results in an error.
- Creating annotations results in an error.
Because of these limitations, it is recommended that you disable these functionalities by following these steps:
- In the `viewer.permissions` set `allowSaveFile` to `false`. Review `allowSaveFile` in the [viewer.permissions](../reference/README.mdx#viewerpermissions) reference documentation.
- In the [WebViewerOptions](../reference/README.mdx#webvieweroptions) remove all entries from the `modules`.
The user interface allows to move, delete, and edit annotations. Saving the document is, however, not possible.
## General limitations
Due to the restrictions of the web environment, the PDF Viewer SDK has specific limitations described in the following sections:
### Color management
The PDF Viewer SDK uses an RGB color space for rendering. There can be some noticeable differences when printing a document that uses CMYK color spaces. As a consequence, the colors of non RGB content can differ slightly from the original when printing.
### System fonts
A font referenced in a PDF file can be either embedded or it is assumed to be present on the host system. Due to browser protection mechanisms, downloaded JavaScript such as the PDF Viewer SDK is not allowed to directly access system fonts. The PDF Viewer SDK analyzes the referenced fonts and replaces them with one of the standard fonts packaged with the PDF Viewer SDK. Consequently, due to this replacement glyph shapes can be altered or not rendered at all. For example: The CJK characters, Cyrillic and some other alphabets.
Texts that use non embedded fonts which use special glyphs can be rendered distorted or not at all.
:::info To avoid described issue
Convert PDF files to PDF/A format before viewing. PDF/A embeds all fonts to the file.
:::
## Custom translations
Parametrize the PDF Viewer SDK in the predefined languages English, German, French, and Italian.
Furthermore, you can define a custom translation. Translations are stored in files of the form `translations.[language].json` that have to reside in the same directory as the WebAssembly (for example, in `window.PDFTOOLS_FOURHEIGHTS_PDFVIEWING_BASEURL`). Set the language used in `language` of the `viewer.general`. For more information, see [viewer.general](../reference/README.mdx#viewergeneral) reference documentation.
If a key in the `translations.[language].json` is missing, PDF Viewer SDK throws an error. You can remove the translation files that are not used.
## Keyboard shortcuts
The PDF Viewer SDK provides the possibility to customize keyboard shortcuts.
In some cases, a shortcut is only available when you enable corresponding option. For example, `shortcuts.print` is only effective when `viewer.permissions.allowPrinting` is set to `true`.
To specify your keyboard shortcuts, use the following structure:
```javascript
KeyboardShortcutBinding {
key: string
altKey?: boolean
ctrlKey?: boolean
shiftKey?: boolean
}
```
Note that the `?` signifies an optional parameter.
:::tip Review reference documentation
For more information about specifiable shortcuts, review the [shortcuts](../reference/README.mdx#shortcuts) interface reference documentation.
:::
### Example configurations of shortcuts
Example configurations of [WebViewerOptions](../reference/README.mdx#webvieweroptions).
Use default shortcut configuration:
```javascript
"viewer": {
}
```
Disable all shortcuts:
```javascript
"viewer": {
"shortcuts": null
}
```
Disable specific shortcuts:
```javascript
"viewer": {
"shortcuts":{
"print": null,
"rotateView": null
}
}
```
Change key binding:
```javascript
"viewer": {
"shortcuts":{
"zoomIn": { "key": "+" },
"zoomOut": { "key": "-" },
"nextPage": { "key": "PageDown" },
"previousPage": { "key": "PageUp" },
"save": {
"key": "s",
"altKey": false,
"ctrlKey": true,
"shiftKey": false,
}
}
}
```
## Custom buttons
You can define custom buttons in the [Document bar](../interface/document-bar.mdx), the [Information bar](../interface/information-bar.mdx), and in the [Annotation bar](../interface/annotation-bar.mdx).
To specify your custom buttons, use the following structure:
```javascript
CustomButton {
icon: string
text: string
onClick: () => void
}
```
### Example configurations of custom buttons
Example configurations of [WebViewerOptions](../reference/README.mdx#webvieweroptions).
Adding a close button to the Information bar:
```javascript
const options = {
viewer: {
customButtons: {
documentbar: [],
informationbar: [
{
icon: 'images/close-icon.svg'
text: 'Close document'
onClick: () => {
pdfViewer.close()
}
}
],
annotationbar: []
}
}
}
const pdfViewer = new PdfWebViewer(document.getElementById('pdfviewer'), '', options)
```
---
## Interface walkthrough
import useBaseUrl from '@docusaurus/useBaseUrl';
import DocCardList from '@theme/DocCardList';
Learn how to navigate pages and documents, search and add annotations by reading descriptions of specific features of the PDW Viewer SDK such as the document bar, navigation bar, annotation bar, and the information bar.
## Graphical user interface
The graphical user interface (GUI) of the PDF Viewer SDK has the following format with various elements collapsing or disappearing depending on the size of the device.
PDF Viewer SDK interface on a desktop:
PDF Viewer SDK interface on a tablet:
PDF Viewer SDK interface on a mobile device:
:::info
You can configure various attributes of the GUI, such as language, position of the annotation bar, and tooltips in the [viewer.general](../reference/README.mdx#viewergeneral).
:::
↵ Enter key.
Configure the search by clicking the wrench icon using the:
- **Case sensitive**: Enable case sensitive search.
- **Wrap search**: Enable whether the search hits wraps from the end of the document to the beginning.
## Information pane
The information pane's visibility is toggled by clicking on the information pane button. When displayed, this bar includes the following tabs:
- **Thumbnails**: When you activate **Thumbnails** tab, thumbnails of the document pages are displayed in the information pane. Click a thumbnail to navigate to the respective page.
- **Outline**: When you activate the **Outline** tab, the document outline is displayed in the information pane as a tree of potentially expandable outline items, also called **bookmarks**. Clicking the outline item navigates to the destination associated with this item. Depending on the type of destination, this changes the active page and also the zoom factor. Note that not all documents have an outline.
- **Annotations**: When activating the **Annotations** tab, an overview of the document's annotations is displayed in the information pane. In this overview, every annotation consists of the following:
- **Icon**: Equivalent to the icons shown in the [Annotation bar](annotation-bar.mdx), additionally colored by the annotations main color.
- **Author**: Only displayed if set for this annotation.
- **Date and time**: Indicates the time when the annotation was created.
- **Subject**: Only displayed if set for this annotation.
- **Text**: This is the text associated with the annotation.
---
## Navigation bar
Learn how to navigate pages in a document, zoom in pages, fit mode, adjust page layout, rotate a page.
## Page navigation
The pages of a document can be navigated by:
- The arrow buttons in the navigation bar.
- A scrolling action triggered by operating the scroll bars, mouse wheel, and a swipe gesture on touch devices.
- Thumbnails, outline items, and annotation comments displayed in the Information pane.
## Page display
### Zoom
You can adjust the zoom factor by:
- The **+** plus and **-** minus butons.
- The zoom selection drop-down button. You can configure the selection in the [viewer.general](../reference/README.mdx#viewergeneral).
### Fit mode
The view can fit a document's page and thereby change the zoom factor and the scroll position, by selecting one of the following fitting modes:
- **Actual size**: Set the zoom factor to 100%.
- **Fit width**: Set the zoom factor such that width of the current page fits the width of the view.
- **Fit page**: Set the zoom factor such that the current page fits into the view.
### Page layout
You can choose among the following page layouts:
- **Continuous display**: The scrollable area that comprises of all pages of a document. Continuous display has the following subtypes:
- **One column**: Display the pages in a single column.
- **Two column left**: Display the pages side-by-side with odd numbered pages on the left and even numbered pages on the right.
- **Two column right**: Display the pages side-by-side with odd numbered pages on the right and even numbered pages on the left.
- **Single page display**: The scrollable area is confined to a single page or two facing pages.
- **Single page**: Display a single page.
- **Two page left**: Display two pages side-by-side with the odd numbered page on the left and the even numbered page on the right.
- **Two page right**: Display two pages side-by-side with the odd numbered page on the right and the evennumbered page on the left.
Configure the fit modes in the [viewer.general](../reference/README.mdx#viewergeneral).
### Rotation
You can rotate the page using the **rotate** button. This does not modify the document.
---
## Touch handling
Touch handling is enabled on mobile devices. The following sections are an overview of the touch handling in different contexts.
## Touch gestures on document
- **Tap**: A short tap on a menu item or context menu executes the equivalent of a mouse click.
- **Touch move**: A touch and move with one finger scrolls the document up and down or left and right.
- **Two touches**: Two fingers can be used to adjust the zoom by pinching or stretching the distance between the fingers.
- **Two touches move**: A touch and move with two fingers move the document in any direction.
## Touch gestures on annotation
- **Tap**: A short tap on a menu item or context menu executes the equivalent of a mouse click.
- **Touch move**: A touch and move with one finger scrolls the document up and down or left and right.
## Touch gestures while creating annotation
- **Sticky note**: After selecting the sticky note from the annotation bar, tap to place a sticky note at the tapped location.
- **Free text annotation**: - **Sticky note**: After selecting the sticky note from the annotation bar, tap to place a sticky note at the tapped location.
- **Text stamp annotation**: After selecting the text stamp annotation from the annotation bar, touch and drag defines the stamp's size while preserving the correct aspect ratio for the selected text.
- **Highlight annotation**: Text is selected with a touch and drag on the text.
- **Ink annotation**: Touch and drag is used to draw the lines of an ink annotation.
---
## Interface reference
Learn about available options for various configurable parameters in the PDF Viewer SDK reference documentation.
## Enumerations
### PdfPageLayoutMode
| Name | Description |
| -------------- | ----------- |
| SINGLE_PAGE | Display a sinlge page at a time. |
| ONE_COLUMN | Display a column of pages. |
| TWO_COLUMN_LEFT | Display pages as two columns next to each other. The first page is on the left. |
| TWO_COLUMN_RIGHT | Display pages as two columns next to each other. The first page is on the right. |
| TWO_PAGE_LEFT | Display two pages next to each other. The first page is on the left. |
| TWO_PAGE_RIGHT | Display two pages next to each other. The first page is on the right. |
### StampAnnotationColor
| Name | Description |
| ----- | ------------------------------------- |
| GREEN | The stamp annotation has green color. |
| RED | The stamp annotation has red color. |
| BLUE | The stamp annotation has blue color |
## WebViewerOptions
The PDF Viewer SDK lets you configure many options in its `index.html`.
### viewer
#### viewer.general
- `viewer.general.user` Set the name of the user.
- Type: `string`
- Default value: `''` (No user set)
- `viewer.general.language` Set language of the tooltips as a two letter language code. See also [Custom translations](../guides/README.mdx#custom-translations).
- Type: `string`
- Allowed values: `'en'`, `'de'`, `'fr'`, `'it'` and custom languages.
- Default value `'en'`
- `viewer.general.promptOnUnsavedChange` If an opened document has unsaved changes and a user presses the open or close buttons the PDF Viewer SDK displays an **unsaved changes** dialog box. Surpress the dialog box by setting the boolean value of `viewer.general.promptOnUnsavedChange` to `false`.
- Type: `boolean`
- Default value: `true`
- `viewer.general.pageShadow` Define the page shadow. The color is a CSS color string. The unit of the other values are in screen pixel.
- Type: `[CanvasShadowStyles](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowBlur)`
- Default: not set
- Example:
```javascript
CanvasShadowStyles {
shadowBlur: number;
shadowColor: string;
shadowOffsetX: number;
shadowOffsetY: number;
}
```
- `viewer.general.pageShadow` Define the page shadow for the current page. The color is a CSS color string. The unit of the other values are in screen pixel.
- Type: `[CanvasShadowStyles](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowBlur)`
- Default: not set
- Example:
```javascript
CanvasShadowStyles {
shadowBlur: number;
shadowColor: string;
shadowOffsetX: number;
shadowOffsetY: number;
}
```
- `viewer.general.tooltips` Tooltips can be turned on with `'title'` and turned off with `'none'`. If you want use your own CSS stylesheet to configure the tooltips, set `'css'`.
- Type: `string`
- Allowed values: `'none'`, `'title'`, `'css'`
- Default value: `'title'`
- `viewer.general.hidePasswordFormCancelButton` Hide the **Cancel** button in the password dialog for password-protected PDFs.
- Type: `boolean`
- Default value: `false`
#### viewer.sidebar
- `viewer.sidebar.thumbnailNavigation` Define if thumbnails are visible in the [Information pane](../interface/information-bar.mdx#information-pane).
- Type: `boolean`
- Default value: `true`
- `viewer.sidebar.outlineNavigation` Define if outlines are visible in the [Information pane](../interface/information-bar.mdx#information-pane).
- Type: `boolean`
- Default value: `true`
- `viewer.sidebar.annotationNavigation` Define whether annotations are visible in the [Information pane](../interface/information-bar.mdx#information-pane).
- Type: `boolean`|`object`
- Default value: `true`
- `viewer.sidebar.annotationNavigation.textMarkup.preview` Define if the preview for text markup annotations is enabled in the [Information pane](../interface/information-bar.mdx#information-pane).
- Type: `string`
- Allowed values: `'none'`, `'short'`
- Default value: `'none'`
#### viewer.permissions
- `viewer.permissions.allowFileDrop` Specify if the files can be opened with drag and drop.
- Type: `boolean`
- Default value: `true`
- `viewer.permissions.allowSaveFile` Specify if the files can be saved.
- Type: `boolean`
- Default value: `true`
- `viewer.permissions.allowCloseFile` Specify if the files can be closed.
- Type: `boolean`
- Default value: `false`
- `viewer.permissions.allowOpenFile` Specify if the files can be opened.
- Type: `boolean`
- Default value: `true`
- `viewer.permissions.allowPrinting` Specify if the files can be printed.
- Type: `boolean`
- Default value: `false`
- `viewer.permissions.allowExternalLinks` Specifies whether external links in the document are interactive.
- Type: `boolean`
- Default value: `true`
- `viewer.permissions.enableSearch` Set if a file can be searched.
- Type: `boolean`
- Default value: `true`
#### viewer.customButtons
For initial information and examples, review [Custom buttons](../guides/README.mdx#custom-buttons) documentation.
- `viewer.customButtons.documentbar` Add buttons to the [Document bar](../interface/document-bar.mdx).
- Type: `CustomButton[]`
- Default value: empty array
- `viewer.customButtons.informationbar` Add buttons to the [Information pane](../interface/information-bar.mdx).
- Type: `CustomButton[]`
- Default value: empty array
- `viewer.permissions.allowCloseFile` Add buttons to the [Annotation bar](../interface/annotation-bar.mdx).
- Type: `CustomButton[]`
- Default value: empty array
### annotation
- `annotation.defaultStampWidth` Set a width of the [Stamp annotation](../interface/annotation-bar.mdx#stamp-annotation) when it is created. The units used are in PDF points. Size of one point is 1/72 inch, or one inch is 72 points.
- Type: `number`
- Default value: `120`
- `annotation.hideAnnotationSubject` Annotation subject is not visible.
- Type: `boolean`
- Default value: `false`
- `annotation.hideOnDelete` If set as `true` and a user deletes an annotation, the annotation is flagged as hidden and not deleted. If set as `false` the annotation is deleted if a user deletes an annotation.
- Type: `boolean`
- Default value: `false`
- `annotation.onlyAuthorCanEdit` Changes to annotations can only be applied when the current user is the author of the annotation.
- Type: `boolean`
- Default value: `false`
### shortcuts
For general information and examples, review [Keyboard shortcuts](../guides/README.mdx#keyboard-shortcuts).
- `shortcuts.zoomIn` Zoom in a document.
- Type: `KeyboardShortcutBinding` Review [Keyboard shortcuts](../guides/README.mdx#keyboard-shortcuts) for a specific example.
- Default parameter and value: ` { key: '+' }`
- `shortcuts.zoomOut` Zoom out in a document.
- Type: `KeyboardShortcutBinding` Review [Keyboard shortcuts](../guides/README.mdx#keyboard-shortcuts) for a specific example.
- Default parameter and value: ` { key: '-' }`
- `shortcuts.nextPage` Next page.
- Type: `KeyboardShortcutBinding` Review [Keyboard shortcuts](../guides/README.mdx#keyboard-shortcuts) for a specific example.
- Default parameter and value: ` { key: 'PageDown' }`
- `shortcuts.previousPage` Previous page.
- Type: `KeyboardShortcutBinding` Review [Keyboard shortcuts](../guides/README.mdx#keyboard-shortcuts) for a specific example.
- Default parameter and value: ` { key: 'PageUp' }`
- `shortcuts.firstPage` Go to the first page.
- Type: `KeyboardShortcutBinding` Review [Keyboard shortcuts](../guides/README.mdx#keyboard-shortcuts) for a specific example.
- Default parameter and value: ` { key: 'Home' }`
- `shortcuts.lastPage` Go to the last page.
- Type: `KeyboardShortcutBinding` Review [Keyboard shortcuts](../guides/README.mdx#keyboard-shortcuts) for a specific example.
- Default parameter and value: ` { key: 'End' }`
- `shortcuts.scrollUp` Scroll up.
- Type: `KeyboardShortcutBinding` Review [Keyboard shortcuts](../guides/README.mdx#keyboard-shortcuts) for a specific example.
- Default parameter and value: ` { key: 'ArrowUp' }`
- `shortcuts.scrollDown` Scroll down.
- Type: `KeyboardShortcutBinding` Review [Keyboard shortcuts](../guides/README.mdx#keyboard-shortcuts) for a specific example.
- Default parameter and value: ` { key: 'ArrowDown' }`
- `shortcuts.scrollLeft` Scroll left.
- Type: `KeyboardShortcutBinding` Review [Keyboard shortcuts](../guides/README.mdx#keyboard-shortcuts) for a specific example.
- Default parameter and value: ` { key: 'ArrowLeft' }`
- `shortcuts.scrollRight` Scroll right.
- Type: `KeyboardShortcutBinding` Review [Keyboard shortcuts](../guides/README.mdx#keyboard-shortcuts) for a specific example.
- Default parameter and value: ` { key: 'ArrowRight' }`
- `shortcuts.releaseSelection` Release selection.
- Type: `KeyboardShortcutBinding` Review [Keyboard shortcuts](../guides/README.mdx#keyboard-shortcuts) for a specific example.
- Default parameter and value: ` { key: 'Escape' }`
- `shortcuts.copy` Copy selected text.
- Type: `KeyboardShortcutBinding` Review [Keyboard shortcuts](../guides/README.mdx#keyboard-shortcuts) for a specific example.
- Default parameter and value: ` { key: 'c', ctrlKey: 'true' }`
- `shortcuts.print` Open print dialog.
- Type: `KeyboardShortcutBinding` Review [Keyboard shortcuts](../guides/README.mdx#keyboard-shortcuts) for a specific example.
- Default parameter and value: ` { key: 'p', ctrlKey: 'true' }`
- `shortcuts.cancelPrint` Cancel printing.
- Type: `KeyboardShortcutBinding` Review [Keyboard shortcuts](../guides/README.mdx#keyboard-shortcuts) for a specific example.
- Default parameter and value: ` { key: 'Escape' }`
- `shortcuts.resetZoom` Zoom to 100%.
- Type: `KeyboardShortcutBinding` Review [Keyboard shortcuts](../guides/README.mdx#keyboard-shortcuts) for a specific example.
- Default parameter and value: ` { key: 'z', altKey: true }`
- `shortcuts.fitToPage` Fit to page.
- Type: `KeyboardShortcutBinding` Review [Keyboard shortcuts](../guides/README.mdx#keyboard-shortcuts) for a specific example.
- Default parameter and value: ` { key: 'p', altKey: true }`
- `shortcuts.fitToWidth` Fit to width.
- Type: `KeyboardShortcutBinding` Review [Keyboard shortcuts](../guides/README.mdx#keyboard-shortcuts) for a specific example.
- Default parameter and value: ` { key: 'w', altKey: true }`
- `shortcuts.rotateView` Rotate view.
- Type: `KeyboardShortcutBinding` Review [Keyboard shortcuts](../guides/README.mdx#keyboard-shortcuts) for a specific example.
- Default parameter and value: ` { key: 'r', altKey: true }`
- `shortcuts.save` Save or save callback.
- Type: `KeyboardShortcutBinding` Review [Keyboard shortcuts](../guides/README.mdx#keyboard-shortcuts) for a specific example.
- Default parameter and value: ` { key: 's', ctrlKey: true }`
- `shortcuts.search` Search.
- Type: `KeyboardShortcutBinding` Review [Keyboard shortcuts](../guides/README.mdx#keyboard-shortcuts) for a specific example.
- Default parameter and value: ` { key: 'f', ctrlKey: true }`
- `shortcuts.searchNext` Next search match.
- Type: `KeyboardShortcutBinding` Review [Keyboard shortcuts](../guides/README.mdx#keyboard-shortcuts) for a specific example.
- Default parameter and value: ` { key: 'F3' }`
- `shortcuts.searchPrevious` Previous search match.
- Type: `KeyboardShortcutBinding` Review [Keyboard shortcuts](../guides/README.mdx#keyboard-shortcuts) for a specific example.
- Default parameter and value: ` { key: 'F3', shiftKey: true }`
- `shortcuts.closeSearch` Close search.
- Type: `KeyboardShortcutBinding` Review [Keyboard shortcuts](../guides/README.mdx#keyboard-shortcuts) for a specific example.
- Default parameter and value: ` { key: 'Escape' }`
- `shortcuts.toggleSidePane` Toggle side pane.
- Type: `KeyboardShortcutBinding` Review [Keyboard shortcuts](../guides/README.mdx#keyboard-shortcuts) for a specific example.
- Default parameter and value: ` { key: 's', altKey: true }`
- `shortcuts.showAnnotations` Display annotation pane.
- Type: `KeyboardShortcutBinding` Review [Keyboard shortcuts](../guides/README.mdx#keyboard-shortcuts) for a specific example.
- Default parameter and value: ` { key: 'a', altKey: true }`
- `shortcuts.showOutline` Display outline pane.
- Type: `KeyboardShortcutBinding` Review [Keyboard shortcuts](../guides/README.mdx#keyboard-shortcuts) for a specific example.
- Default parameter and value: ` { key: 'o', altKey: true }`
- `shortcuts.showThumbnails` Display thumbnails pane.
- Type: `KeyboardShortcutBinding` Review [Keyboard shortcuts](../guides/README.mdx#keyboard-shortcuts) for a specific example.
- Default parameter and value: ` { key: 't', altKey: true }`
---
## Release notes(Version-4)
Learn about the changes, additions, and fixes in the PDF Viewer SDK.
## Version 4
### 4.3.5
20 August 2025
#### Added
- Added an option to turn off all external hyperlinks while keeping internal links active. Configure this option using the `viewer.permissions.allowExternalLinks` flag in `WebViewerOptions`.
- Introduced a new print option that can exclude annotations when printing documents. By default, the PDF Viewer SDK includes annotations unless you manually turn them off in the print dialog.
- This update adds support for an optional `title` property on stamps. When set, the title displays as a tooltip on hover, improving clarity and accessibility.
- Option to hide the **Cancel** button in the password dialog for password-protected PDFs. Controlled via the `viewer.general.hidePasswordFormCancelButton` flag in `WebViewerOptions`.
#### Changed
- Updated ink annotation behavior so that the PDF Viewer SDK applies strokes immediately. This ensures that if a user starts drawing an ink annotation and attempts to close the viewer, the user receives a notification that unsaved changes may disappear.
#### Fixed
- Fixed an issue where printing documents could result in excess blank pages. The PDF Viewer SDK now prints the correct number of pages.
- The password dialog for password-protected PDF files now works as expected. Entering an incorrect password now displays an error message, and clicking **Cancel** no longer results in an empty viewer.
- Fixed an issue with editing text annotations containing only plain text without styling, where content could disappear. Such annotations now remain intact and editable.
- Disabled radio button highlighting to ensure proper display in form fields.
- Fixed checkbox display in form fields by applying blend mode for widget highlighting.
### 4.3.4
29 January 2025
#### Fixed
- Prior to this update, when you downloaded a PDF Viewer SDK trial version, the trial license included with the PDF Viewer SDK by default was invalid. As a consequence, the SDK displayed an invalid license error. With this update, we replaced the invalid key with a valid key. As a result, you can now test the SDK without encountering an invalid license error.
- The preview panel with thumbnails of PDF files was previously crashing due to a race condition. With this update, the error is handled properly. As a result, previews of PDF files are displayed correctly, and the described error no longer occurs.
### 4.3
24 April 2024
#### Added
- Redaction icon for custom button to call the SDK redaction feature.
- Safari optimizations, HTTP options are now provided on a separate build.
#### Fixed
- You can now resize image stamps to their original size if smaller than a minimal defined size.
- Memory exception happening on large documents in single page mode.
- Issue with saved shape annotations with 1pt width stroke disappearing when editing and reloading multiple times.
- Transparent sticky annotations now have a fallback black color.
### 4.2
13 April 2023
#### Added
- `WebViewerOption` to disable the main toolbar and the annotation toolbar. You can use this option to create your own custom toolbars.
- `viewer.general.disableMainToolbar: boolean`
- `viewer.general.disableAnnotationToolbar: boolean`
- `WebViewerOption` to disable the annotation lock feature.
- `viewer.permissions.allowLockAnnotations: true`
- `viewer.permissions.allowEditLockedAnnotations: false`
- `PdfWebViewer.getSelectedText(): string`. Returns selected text.
- Method `PdfWebViewer.print() void`. Opens the print dialog.
- Method `PdfWebViewer.zoomIn(): void`. Sets the zoom to the closest higher predefined zoom level.
- Method `PdfWebViewer.toggleInformationPane(): void`. Toggles the visibility of the information pane.
- Event `textSelected: string` for `PdfWebViewer`.
- Event `documentClosed: void` for `PdfWebViewer`.
### 4.1
3 March 2023
#### Added
- `WebViewerOption` to highlight the current page in the PDF Viewer SDK.
`viewer.general.currentPageShadow`
`shadowBlur: number`
`shadowColor: string`
`shadowOffsetX: number`
`shadowOffsetY: number`
- The `WebViewerOption` lets you define custom permissions for annotations. You can restrict the permissions to a specific user.
- `annotation.annotationPermissionCallback: (annotation: Annotation, user: string) => boolean`
- **Improved** eraser tool. The radius for the eraser can now be adjusted in the user interface (UI).
### 4.0.1
2 February 2023
#### Fixed
- An issue where `hasChanges()` returned `null` when multiple types of changes were made.
- An issue that prevented from filling the form fields.
- The `textsearch` no longer interprets braces as part of a regular expression unless a regular expression option is enabled.
- Previously, when a page was rotated, stamp annotations could only follow the page rotation. With this update, you can rotate `stampannotations` independently of the page rotation.
- Interaction with annotations on right half of the viewport in SinglePage mode.
### 4.0
14 November 2022
#### Added
- `WebViewerOption` to disable view rotation.
- `viewer.permissions.allowRotateView`
- `WebViewerOption` to disable page layout mode.
- `viewer.permissions.enablePageLayoutMode`
- `WebViewerOption` to open the page navigation with a specific tab.
- `viewer.sidebar.selectedNavigation?: 'thumbnail' | 'outline' | 'annotation'`
- **Improved** edit existing annotations.
- Shape annotations
- Ink annotations
- Highlight annotations
- Tool to create rectangular highlight annotations.
- Properties for `HttpOptions` for the `open` method:
- `mode?: 'cors' | 'no-cors' | 'same-origin'`
- `cache? 'default' | 'no-cache' | 'reload' | 'force-cache' | 'only-if-cached'`
- `credentials?: 'include' | 'same-origin' | 'omit'`
- `redirect?: 'manual' | 'follow' | 'error'`
- `referrerPolicy?: 'no-referrer' | 'no-referrer-when-downgrade' | 'origin' | 'origin-when-cross-origin' | 'same-origin' | 'strict-origin' | 'strict-origin-when-cross' | 'unsafe-url'`
- Properties for `ViewOptions` for the `open` method:
- `initialPageNumber?: number`
- `initialZoom?: number`
- **Improved** general visual appearance and user experience.
## Version 3
### 3.11.1
10 January 2023
#### Added
- Option `WebViewerOptions.viewer.permissions.allowCopyText` to prevent copying of text from the PDF file. The default value is `true`.
#### Fixed
- When calling `startSearch` multiple times, the search input field is now updated with the new search term.
- An issue that prevented the PDF Viewer SDK from evaluation without configuring a license key.
### 3.11
20 October 2022
#### Added
- Method `PdfWebViewer.getPageNumber(): number | null`.
Get the currently most visible page.
- Method `PdfWebViewer.getZoom(): number | null`.
Get the viewer zoom.
- Method `PdfWebViewer.getFitMode(): PdfFitMode | null`.
Get the current fit mode.
- Method `PdfWebViewer.getPageLayoutMode(): PdfPageLayoutMode | null`.
Get the current page layout mode.
- Method `PdfWebViewer.getRotation(): number | null`.
- Get the viewer rotation property value.
- Method `PdfWebViewer.hasChanges(): DocumentChange | null`.
- Check whether there are unsaved changes in the document.
- Method `PdfWebViewer.showInformationPane(selectedPane?: 'thumbnail' | 'outline' | 'annotation'): void`.
Opens the information pane and selects the given pane.
- Method `PdfWebViewer.hideInformationPane(): void`.
Closes the information pane.
- Method `PdfWebViewer.startSearch(text: string, searchOptions: SearchOptions): void`.
Opens the search tool bar and starts a new search with the given text.
- Method `PdfWebViewer.nextSearchMatch()`.
Highlights the next search result
- Method `PdfWebViewer.previousSearchMatch()`.
Highlights the previous search result
- Method `PdfWebViewer.endSearch()`.
Stops the current search and closes the search tool bar
- New events for `PdfWebViewer`.
`pageNumberChanged: number`
`zoomChanged: number`
`rotationChanged: number`
`fitModeChanged: PdfFitMode`
`pageLayoutModeChanged: PdfPageLayoutMode`
`documentChanged: void`
### 3.10.1
5 October 2022
#### Fixed
- Annotation filtering that yielded unpredictable results when filtering annotations from PDF files with duplicate annotation names. This described issue has been fixed.
- Saving to FDF format no longer returns errors if any annotations are illegal to save to FDF, but only if it is actually being saved.
### 3.10
28 September 2022
#### Added
- Eraser tool for deleting individual lines in free-hand drawings.
- Translation keys available for the eraser tool:
- `eraser.begin`
- `eraser.deleteFreeDrawingLines`
- Keyboard shortcut to cancel the current annotation tool. The default shortcut binding is Esc .
- `shortcuts.cancelEditAnnotation`
- Method `open(pdfFile, fdfFiles?, password?, renderOptions?, viewOptions?).`
Open a PDF and optionally one or more associated FDFs.
- Method `save(saveOptions)`.
Return the opened PDF as `Blob` to be used. For example to save the file.
#### Changed
- **Deprecated** `openFile` use the new `open` method instead.
- **Deprecated** `openFDF` use the new `open` method instead.
- **Deprecated** `saveFile` use the new `save` method instead.
### 3.9
8 November 2022
#### Added
- Preview for text markup annotations (highlight, underline, strike out) in annotation information pane.
`sidebar.annotationNavigation.textMarkup.preview`
### 3.8
15 June 2022
- Support custom buttons, configurable with the following options:
`viewer.customButtons.documentbar`
`viewer.customButtons.informationbar`
`viewer.customButtons.annotationbar`
### 3.7
18 May 2022
#### Added
- Support for rectangular text selection, configurable with the option.
`viewer.general.rectangularTextSelection`
### 3.6
21 April 2022
#### Added
- Translation key `contextbar.openPopup`.
- Support for rotating free-text annotations.
- Support for custom shortcuts. Specifiable shortcuts in the WebViewerOptions:
- `shortcuts.zoomIn`
- `shortcuts.zoomOut`
- `shortcuts.nextPage`
- `shortcuts.previousPage`
- `shortcuts.firstPage`
- `shortcuts.lastPage`
- `shortcuts.scrollUp`
- `shortcuts.scrollDown`
- `shortcuts.scrollLeft`
- `shortcuts.scrollRight`
- `shortcuts.releaseSelection`
- `shortcuts.copy`
- `shortcuts.print`
- `shortcuts.cancelPrint`
- `shortcuts.resetZoom`
- `shortcuts.fitToPage`
- `shortcuts.fitToWidth`
- `shortcuts.rotateView`
- `shortcuts.save`
- `shortcuts.search`
- `shortcuts.searchNext`
- `shortcuts.searchPrevious`
- `shortcuts.closeSearch`
- `shortcuts.toggleSidePane`
- `shortcuts.showAnnotations`
- `shortcuts.showOutline`
- `shortcuts.showThumbnails`
#### Changed
- Rendering of form fields. Interactive form fields are now highlighted.
### 3.5
1 April 2022
#### Added
- You can now evaluate (try out) the PDF Viewer SDK without a license key.
#### Changed
- When operating without a productive license. A watermark is displayed if no license key is set or when setting an evaluation license key. An evaluation license with disabled watermark can be provided upon request.
### 3.4
23 February 2022
#### Added
The PDF Viewer SDK is now available on npmjs.com.
### 3.3
#### Added
- Improved ink annotations:
- Improved resizing behavior.
- Improved bounding box computation for large line widths.
- Improved drawing of small ink lines.
- Line caps and joins changed to `round`.
### 3.2
#### Added
- Improved mobile and responsive view:
- Responsive collapsing of toolbars.
- The outline-pane is now available for small mobile devices.
- The annotations-pane is now available for small mobile devices.
#### Changed
- A complete redesign of the CSS.
- Existing customer-specific style adjustments can be revised.
- The font family is no longer overwritten but inherited from the document.
### 3.1
#### Added
- Support for tooltips for all supported languages (English, German, French, and Italian). You can set the new tooltip mode with `WebViewerOptions.viewer.general.tooltips`. Allowed values are:
- Enable tooltips: `'title'`
- Disable tooltips: `'none'`
- A CSS to configure the tooltips. Use: `'css'`
- Improved translation to French.
- New support for a close button. This button can be enabled or disabled with the new option `WebViewerOptions.permissions.allowCloseFile`. The new callback `onCloseFileButtonClicked?()` can be optionally used.
- Support for external translation files in JSON format. Supported keys are:
- `openFile.dropFileHere`
- `openFile.openFileDisabled`
- `openFile.openDocument`
- `openFile.selectFile`
- `openFileError.description`
- `openFileError.ok`
- `loadFile.title`
- `saveFile.title`
- `passwordForm.description`
- `passwordForm.ok`
- `passwordForm.cancel`
- `passwordForm.passwordRequiredError`
- `passwordForm.invalidPasswordError`
- `applicationLoader.title`
- `applicationError.title`
- `applicationError.reload`
- `applicationError.defaultMessage`
- `applicationError.invalidLicense`
- `unsavedChanges.description`
- `unsavedChanges.save`
- `unsavedChanges.dontSave`
- `unsavedChanges.cancel`
- `search.inputPlaceholder`
- `search.optionCaseSensitive`
- `search.optionWrap`
- `search.optionRegularExpression`
- `search.previousMatch`
- `search.nextMatch`
- `search.options`
- `sideNavigation.thumbnails`
- `sideNavigation.outline`
- `sideNavigation.annotation`
- `sideNavigation.annotation.page`
- `sideNavigation.annotation.history`
- `pageLayoutMode.oneColumn`
- `pageLayoutMode.singlePage`
- `pageLayoutMode.twoColumnLeft`
- `pageLayoutMode.twoColumnRight`
- `pageLayoutMode.twoPageLeft`
- `pageLayoutMode.twoPageRight`
- `fitMode.page`
- `fitMode.width`
- `fitMode.none`
- `toolbar.openDocument`
- `toolbar.closeDocument`
- `toolbar.print`
- `toolbar.saveDocument`
- `toolbar.nextPage`
- `toolbar.previewsPage`
- `toolbar.pageOf`
- `toolbar.zoom`
- `toolbar.zoomIn`
- `toolbar.zoomOut`
- `toolbar.rotateView`
- `toolbar.search`
- `toolbar.toggleSidePane`
- `annotText.add`
- `annotFreeDrawing.add`
- `annotFreeDrawing.opacity`
- `annotFreeDrawing.strokeWidth`
- `annotFreeDrawing.undo`
- `annotFreeDrawing.addNew`
- `annotFreeDrawing.deleteLine`
- `annotFreeText.add`
- `annotFreeText.edit`
- `annotFreeText.fontFamily`
- `annotFreeText.fontSize`
- `annotFreeText.fontColor`
- `annotFreeText.bgColor`
- `annotFreeText.borderWidth`
- `annotFreeText.alignLeft`
- `annotFreeText.alignCenter`
- `annotFreeText.alignRight`
- `annotFreeText.bold`
- `annotFreeText.italic`
- `annotFreeText.underline`
- `annotFreeText.lock`
- `annotFreeText.unlock`
- `annotFreeText.subjectPlaceholder`
- `annotHighlight.add`
- `annotHighlight.highlight`
- `annotHighlight.underline`
- `annotHighlight.squiggly`
- `annotHighlight.strikeOut`
- `annotStamp.add`
- `annotStamp.chooseStamp`
- `annotShape.add`
- `annotShape.addRectangle`
- `annotShape.addEllipse`
- `annotShape.strokeColor`
- `annotShape.strokeWidth`
- `annotShape.strokeStyle`
- `annotShape.bgColor`
- `annotImage.add`
- `annotPopup.delete`
- `annotPopup.lock`
- `annotPopup.unlock`
- `annotPopup.color`
- `annotPopup.subjectPlaceholder`
- `annotPopup.contentPlaceholder`
- `contextbar.rotate`
- `contextbar.editPopup`
- `contextbar.addPopup`
- `contextbar.deletePopup`
- `contextbar.lock`
- `contextbar.unlock`
- `contextbar.delete`
- `contextbar.confirmDelete`
- `contextbar.cancelDelete`
- `contextbar.copyText`
- `contextbar.highlightText`
- `contextbar.underlineText`
- `contextbar.squigglyText`
- `contextbar.strikeOutText`
- `errors.invalidLicense`
- `stamptext.approved`
- `stamptext.notApproved`
- `stamptext.draft`
- `stamptext.final`
- `stamptext.completed`
- `stamptext.confidential`
- `stamptext.forPublic`
- `stamptext.notForPublic`
- `stamptext.void`
- `stamptext.forComment`
- `stamptext.preliminaryResults`
- `stamptext.informationOnly`
- `print.title`
- `print.all`
- `print.current`
- `print.range`
- `print.invalid`
- `print.print`
- `print.cancel`
- `border.none`
#### Changed
- Icons for freetext annotation and fitmode page.
## Version 2
### Added
- Filling form fields support:
- Text fields
- Check boxes
- Radio buttons
- List boxes
- Drop down
Enable or disable filling form fields with the option `WebViewerOptions.forms.enabled`.
- Support for pre-configuring stamp annotations created from pages of a PDF file.
- Viewing-only mode with disabled editing of annotations and form filling capability. This mode is entered automatically if the license key does not support editing. Additionally, you can enable or disable the viewing-only mode with the option `WebViewerOptions.viewer.general.viewOnly`.
- Support for preventing the modification and deletion of all annotations except the currently configured author's. You can enable or disable this restriction with the new option `WebViewerOptions.annotation.onlyAuthorCanEdit`.
- Double-click selects words.
- Improved scrolling sensitivity for mobile devices.
- French translation.
### Changed
- In the side pane, the title texts are substituted with icons.
- In the page mode selection user interface, the texts are substituted with icons.