File Attachment
- 3 minutes to read
This document introduces a file attachment, describes actions that can be performed on attachments, and lists the attachments viewer options.
The document consists of the following sections.
Overview
An attachment is a file that is attached to a PDF document. The PDF Viewer shows the file attachments in the Attachments panel (the attachments viewer).
Important
The attachments viewer is hidden if a PDF document does not contain a file attachment.
The PDF Document API can generate a PDF document and attach a file to this PDF. For more information, see the How to: Attach a File to a Document example.
The Attachments panel can contain any kind of file (including PDFs) and any number of them. The panel also includes basic information about files (e.g., name, description, size).
Open an attachment
To open and view a file attachment, you need an application that supports the corresponding file format to be installed on your computer. To view an attachment, do one of the following.
Double click the attached file.
or
Select the file and click the “Open file in its native application” icon on the Attachments panel.
The Security Warning message appears. It warns you that the PDF Viewer will use an external application to open the attached file.
Click Yes to open the attached file (e.g., the “Logo.jpg”), otherwise click No.
This opens the attachment.
You can customize the open attachment behavior (e.g., to hide the Security Warning message box) by handling the PdfViewerControl.AttachmentOpening event.
Save an attachment
The file attachment can be saved to your disk. To do this, select the file and click the “Save attachment” icon, as shown below.
The Save As dialog appears.
Choose the file attachment location on the disk, specify the file name, and click Save.
Customization
This section describes properties that can be used to customize attachments of a PDF Viewer.
To customize attachment behavior on the Attachments panel (attachments viewer), access a PdfAttachmentsViewerSettings object using the PdfViewerControl.AttachmentsViewerSettings property.
The main settings are detailed in the following table.
| Member | Description |
|---|---|
| PdfAttachmentsViewerSettings.HideAttachmentsViewer | Gets or sets a value which specifies whether the PDF attachments viewer is hidden. |
| PdfAttachmentsViewerSettings.HideAfterUse | Gets or sets a value which specifies whether the PDF attachments viewer panel is hidden after opening or saving an attached file. |
| PdfAttachmentsViewerSettings.ActualHideAfterUse | Gets the actual value of the attachments viewer panel visibility after opening or saving an attached file. |
| PdfAttachmentsViewerSettings.AttachmentsViewerStyle | Gets or sets a style applied to the attachments viewer. This is a dependency property. |
You can change the attachments viewer’s visible state for the PDF Viewer using the PdfAttachmentsViewerSettings.AttachmentsViewerState (specifies the current visible state of the attachments viewer) and PdfAttachmentsViewerSettings.AttachmentsViewerInitialState (specifies the attachments viewer visibility behavior after loading new PDF document) properties. These properties can be set to one of the following values.
- Expanded - the attachments viewer panel is expanded
- Collapsed - the attachments viewer panel is collapsed
- Visible – the attachments viewer panel is visible
The PdfAttachmentsViewerSettings.AttachmentsViewerInitialState property can also be set to the additional Null value (the Default mode). In this mode, the PdfAttachmentsViewerSettings.AttachmentsViewerState property is set to Collapsed if a PDF document contains attachments. If a PDF document does not have a file attachment, the attachments viewer is hidden (the PdfAttachmentsViewerSettings.HideAttachmentsViewer property is set to true).