HPS::Publish::DocumentKit

class HPS::Publish::DocumentKit : public HPS::SprocketKit

The DocumentKit class is a user space object. It acts as the root container for all pages in a Publish PDF.

Public Functions

DocumentKit &AddAttachment(char const *in_filename, char const *in_description)

Adds an attachment to the document. If there is an existing attachment on the document with the given filename, it will get overwritten. This corresponds to the value that will be passed to A3DPDFDocumentAddFileAttachment.

Parameters

in_filename – UTF8-encoded filename of the file to be attached.
in_description – UTF8-encoded description of the file to be attached.

Returns

A reference to this DocumentKit.

DocumentKit &AddAttachments(size_t in_count, UTF8 const in_filenames[], UTF8 const in_descriptions[])

Adds a list of attachments to the document. If there is an existing attachment on the document with a filename which is in the given list, it will get overwritten. These correspond to values that will be passed to A3DPDFDocumentAddFileAttachment.

Parameters

in_count – Size of the following arrays.
in_filenames – Filenames of the files to be attached.
in_descriptions – Descriptions of the files to be attached.

Returns

A reference to this DocumentKit.

DocumentKit &AddAttachments(UTF8Array const &in_filenames, UTF8Array const &in_descriptions)

Adds a list of attachments to the document. If there is an existing attachment on the document with a filename which is in the given list, it will get overwritten. These correspond to values that will be passed to A3DPDFDocumentAddFileAttachment.

Parameters

in_filenames – Filenames of the files to be attached.
in_descriptions – Descriptions of the files to be attached.

Returns

A reference to this DocumentKit.

DocumentKit &AddDataTable(DataTableKit const &in_data_table)

Adds an data table to the document.

Parameters: in_data_table – Data Table to be added into the document.
Returns: A reference to this DocumentKit.

DocumentKit &AddDataTables(DataTableKitArray const in_data_table)

Adds data tables to the document.

Parameters: in_data_table – Data Tables to be added into the document.
Returns: A reference to this DocumentKit.

DocumentKit &AddIconImage(char const *in_name, ImageKit const &in_image)

Adds an icon image to the document. If there is an existing icon image on the document with the given name, it will get overwritten. This corresponds to the value that will be passed to A3DPDFDocumentAddImageAsIcon.

Parameters

in_name – UTF8-encoded name of the icon image to be attached.
in_image – Image to be attached as an icon.

Returns

A reference to this DocumentKit.

DocumentKit &AddIconImages(size_t in_count, UTF8 const in_names[], ImageKit const in_images[])

Adds icon images to the document. If there is an existing icon image on the document with a name which is in the given list, it will get overwritten. These correspond to the values that will be passed to A3DPDFDocumentAddImageAsIcon.

Parameters

in_count – Size of the following arrays.
in_names – Names of the icon images to be attached.
in_images – Images to be attached as icons.

Returns

A reference to this DocumentKit.

DocumentKit &AddIconImages(UTF8Array const &in_names, ImageKitArray const &in_images)

Adds icon images to the document. If there is an existing icon image on the document with a name which is in the given list, it will get overwritten. These correspond to the values that will be passed to A3DPDFDocumentAddImageAsIcon.

Parameters

in_names – Names of the icon images to be attached.
in_images – Images to be attached as icons.

Returns

A reference to this DocumentKit.

DocumentKit &AddJavaScript(char const *in_script_name, char const *in_source, Source::Type in_type = Source::Type::Code)

Adds a named JavaScript source or file to the document. If there is an existing script on the document with the given name, it will get overwritten. This corresponds to the value that will be passed to A3DPDFDocumentAddJavascriptFromString.

Parameters

in_script_name – UTF8-encoded script name to be added to the document.
in_source – UTF8-encoded JavaScript source or file (depending on the following argument) to be added to the document.
in_type – The types of the preceding argument. Defaults to Source::Type::Code.

Returns

A reference to this DocumentKit.

DocumentKit &AddJavaScript(size_t in_count, UTF8 const in_script_names[], UTF8 const in_sources[], Source::Type const in_types[])

Adds a list of named JavaScript sources or files to the document. If there is an existing script on the document with a name which is in the given list, it will get overwritten. These correspond to values that will be passed to A3DPDFDocumentAddJavascriptFromString.

Parameters

in_count – Size of the following arrays.
in_script_names – Script names to be added to the document.
in_sources – JavaScript sources and/or files (depending on the corresponding entry in the following argument) to be added to the document.
in_types – Types for each item in the preceding argument array.

Returns

A reference to this DocumentKit.

DocumentKit &AddJavaScript(UTF8Array const &in_script_names, UTF8Array const &in_sources, SourceTypeArray const &in_types)

Adds a list of named JavaScript sources or files to the document. If there is an existing script on the document with a name which is in the given list, it will get overwritten. These correspond to values that will be passed to A3DPDFDocumentAddJavascriptFromString.

Parameters

in_script_names – Script names to be added to the document.
in_sources – JavaScript sources and/or files (depending on the corresponding entry in the following argument) to be added to the document.
in_types – Types for each item in the preceding argument array.

Returns

A reference to this DocumentKit.

DocumentKit &AddPage(PageKit const &in_page)

Adds the given page to the document. This will append the page after any existing pages on the document. This corresponds to the value that will be passed to A3DPDFDocumentAppendNewPage or A3DPDFDocumentAppendPageFromPDFFileEx.

Parameters: in_page – Page to add to the document.
Returns: A reference to this DocumentKit.

DocumentKit &AddPages(PageKitArray const &in_pages)

Adds the given pages to the document. This will append the pages after any existing pages on the document. These correspond to values that will be passed to A3DPDFDocumentAppendNewPage or A3DPDFDocumentAppendPageFromPDFFileEx.

Parameters: in_pages – Pages to add to the document.
Returns: A reference to this DocumentKit.

DocumentKit &AddPages(size_t in_count, PageKit const in_pages[])

Adds the given pages to the document. This will append the pages after any existing pages on the document. These correspond to values that will be passed to A3DPDFDocumentAppendNewPage or A3DPDFDocumentAppendPageFromPDFFileEx.

Parameters

in_count – Size of the following array.
in_pages – Pages to add to the document.

Returns

A reference to this DocumentKit.

DocumentKit(): The default constructor creates an empty DocumentKit object.

DocumentKit(DocumentKit &&in_kit)

The move constructor creates a DocumentKit by transferring the underlying object of the rvalue reference to this DocumentKit.

Parameters: in_kit – An rvalue reference to a DocumentKit to take the underlying object from.

DocumentKit(DocumentKit const &in_kit)

The copy constructor creates a new DocumentKit object that contains the same settings as the source DocumentKit.

Parameters: in_kit – The source DocumentKit to copy.

virtual bool Empty() const

Indicates whether this DocumentKit has any values set on it.

Returns: true if no values are set on this DocumentKit, false otherwise.

bool Equals(DocumentKit const &in_kit) const

Check if the source DocumentKit is equivalent to this DocumentKit.

Parameters: in_kit – The source DocumentKit to compare to this DocumentKit.
Returns: true if the objects are equivalent, false otherwise.

inline virtual HPS::Type ObjectType() const

This function returns the type the object, as declared (if the object is derived, this does not give the true type of the derived object).

Returns: The declared type of the object in question, which may differ from the true, underlying type.

bool operator!=(DocumentKit const &in_kit) const

Check if the source DocumentKit is not equivalent to this DocumentKit.

Parameters: in_kit – The source DocumentKit to compare to this DocumentKit.
Returns: true if the objects are not equivalent, false otherwise.

DocumentKit &operator=(DocumentKit &&in_kit)

The move assignment operator transfers the underlying object of the rvalue reference to this DocumentKit.

Parameters: in_kit – An rvalue reference to a DocumentKit to take the underlying object from.
Returns: A reference to this DocumentKit.

DocumentKit &operator=(DocumentKit const &in_kit)

Copies the source DocumentKit into this DocumentKit.

Parameters: in_kit – The source DocumentKit to copy.
Returns: A reference to this DocumentKit.

bool operator==(DocumentKit const &in_kit) const

Check if the source DocumentKit is equivalent to this DocumentKit.

Parameters: in_kit – The source DocumentKit to compare to this DocumentKit.
Returns: true if the objects are equivalent, false otherwise.

void Set(DocumentKit const &in_kit)

Copies the source DocumentKit into this DocumentKit.

Parameters: in_kit – The source DocumentKit to copy.

DocumentKit &SetInformation(char const *in_title, char const *in_author, char const *in_subject, char const *in_creator)

Sets the title, author, subject and creator for this document. These corresponds to the values that will be passed to A3DPDFDocumentInformationData::m_pcTitle, A3DPDFDocumentInformationData::m_pcAuthor, A3DPDFDocumentInformationData::m_pcSubject, and A3DPDFDocumentInformationData::m_pcCreator (respectively).

Parameters

in_title – UTF8-encoded title string to set on the document.
in_author – UTF8-encoded author string to set on the document.
in_subject – UTF8-encoded subject string to set on the document.
in_creator – UTF8-encoded creator string to set on the document.

Returns

A reference to this DocumentKit.

DocumentKit &SetPage(PageKit const &in_page)

Adds the given page to the document. This will replace all pages (if any) which are already on the document. This corresponds to the value that will be passed to A3DPDFDocumentAppendNewPage or A3DPDFDocumentAppendPageFromPDFFileEx.

Parameters: in_page – Page to add to the document.
Returns: A reference to this DocumentKit.

DocumentKit &SetPages(PageKitArray const &in_pages)

Adds the given pages to the document. This will replace all pages (if any) which are already on the document. These correspond to values that will be passed to A3DPDFDocumentAppendNewPage or A3DPDFDocumentAppendPageFromPDFFileEx.

Parameters: in_pages – Pages to add to the document.
Returns: A reference to this DocumentKit.

DocumentKit &SetPages(size_t in_count, PageKit const in_pages[])

Adds the given pages to the document. This will replace all pages (if any) which are already on the document. These correspond to values that will be passed to A3DPDFDocumentAppendNewPage or A3DPDFDocumentAppendPageFromPDFFileEx.

Parameters

in_count – Size of the following array.
in_pages – Pages to add to the document.

Returns

A reference to this DocumentKit.

DocumentKit &SetPasswords(char const *in_user_password, char const *in_owner_password)

Sets the passwords for this document. This corresponds to the value that will be passed to A3DPDFDocumentSetPassword.

Parameters

in_user_password – UTF8-encoded password string required when opening, modifying or printing the document. If an empty string is specified, no password will be required.
in_owner_password – UTF8-encoded password string required when changing security features of document. If an empty string is specified, no password will be required.

Returns

A reference to this DocumentKit.

DocumentKit &SetPermissions(PermissionTypeArray const &in_permissions)

Sets document permissions. This correspond to the values that will be passed to A3DPDFDocumentSetDocumentPermissions.

Parameters: in_permissions – The permissions to be set on the document.
Returns: A reference to this DocumentKit.

DocumentKit &SetPermissions(size_t in_count, Permission::Type const in_permissions[])

Sets document permissions. This correspond to the values that will be passed to A3DPDFDocumentSetDocumentPermissions.

Parameters

in_count – Size of the following array.
in_permissions – The permissions to be set on the document.

Returns

A reference to this DocumentKit.

void Show(DocumentKit &out_kit) const

Copies this DocumentKit into the given DocumentKit.

Parameters: out_kit – The DocumentKit to populate with the contents of this DocumentKit.

bool ShowAttachments(UTF8Array &out_filenames, UTF8Array &out_descriptions) const

Shows the attachments on the document.

Parameters

out_filenames – Filenames of the attachments on the document.
out_descriptions – Descriptions of the attachments on the document.

Returns

true if attachments were specified, false otherwise.

bool ShowDataTables(DataTableKitArray &out_data_tables) const

Shows data tables on the document

Parameters: out_data_tables – Data tables on the document.
Returns: true if data tables were set, false otherwise.

bool ShowIconImages(UTF8Array &out_names, ImageKitArray &out_images) const

Shows the icon images on the document.

Parameters

out_names – Names of the icon images on the document.
out_images – Icon images on the document.

Returns

true if icon images were specified, false otherwise.

bool ShowInformation(UTF8 &out_title, UTF8 &out_author, UTF8 &out_subject, UTF8 &out_creator) const

Shows the document title, author, subject and creator.

Parameters

out_title – Title of the document
out_author – Author of the document
out_subject – Subject of the document
out_creator – Creator of the document

Returns

true if a title, author, subject and creator were specified, false otherwise.

bool ShowJavaScript(UTF8Array &out_script_names, UTF8Array &out_sources, SourceTypeArray &out_types) const

Shows the JavaScript sources and/or files on the document.

Parameters

out_script_names – Script names on the document.
out_sources – JavaScript sources and/or files on the document.
out_types – Types for each item in the preceding array.

Returns

True if this setting was specified, otherwise false.

Returns

true if scripts were specified, false otherwise.

bool ShowPages(PageKitArray &out_pages) const

Shows the pages on the document.

Parameters: out_pages – Pages on the document.
Returns: true if pages were specified, false otherwise.

bool ShowPasswords(UTF8 &out_user_password, UTF8 &out_owner_password) const

Shows the document passwords.

Parameters

out_user_password – User password of the document.
out_owner_password – Owner password of the document.

Returns

true if passwords were specified, false otherwise.

bool ShowPermissions(PermissionTypeArray &out_permissions) const

Shows permissions on the document

Parameters: out_permissions – Permissions on the document.
Returns: true if permissions were specified, false otherwise.

DocumentKit &UnsetAttachment(char const *in_filename)

Removes the attachment with a given filename from the document.

Parameters: in_filename – UTF8-encoded filename of attachment to remove from the document.
Returns: A reference to this DocumentKit.

DocumentKit &UnsetAttachments()

Removes all attachments from the document.

Returns: A reference to this DocumentKit.

DocumentKit &UnsetAttachments(size_t in_count, UTF8 const in_filenames[])

Removes the attachments with the given filenames from the document.

Parameters

in_count – Size of the following array.
in_filenames – Filenames of attachments to remove from the document.

Returns

A reference to this DocumentKit.

DocumentKit &UnsetAttachments(UTF8Array const &in_filenames)

Removes the attachments with the given filenames from the document.

Parameters: in_filenames – Filenames of attachments to remove from the document.
Returns: A reference to this DocumentKit.

DocumentKit &UnsetDatatables()

Removes Data Table settings from the document.

Returns: A reference to this DocumentKit.

DocumentKit &UnsetEverything()

Removes all data from the document.

Returns: A reference to this DocumentKit.

DocumentKit &UnsetIconImage(char const *in_name)

Removes the icon image with a given name from the document.

Parameters: in_name – UTF8-encoded name of icon image to remove from the document.
Returns: A reference to this DocumentKit.

DocumentKit &UnsetIconImages()

Removes all icon images from the document.

Returns: A reference to this DocumentKit.

DocumentKit &UnsetIconImages(size_t in_count, UTF8 const in_names[])

Removes the icon images with the given names from the document.

Parameters

in_count – Size of the following array.
in_names – Names of icon images to remove from the document.

Returns

A reference to this DocumentKit.

DocumentKit &UnsetIconImages(UTF8Array const &in_names)

Removes the icon images with the given names from the document.

Parameters: in_names – Names of icon images to remove from the document.
Returns: A reference to this DocumentKit.

DocumentKit &UnsetInformation()

Removes the document title, author, subject and creator.

Returns: A reference to this DocumentKit.

DocumentKit &UnsetJavaScript()

Removes all scripts from the document.

Returns: A reference to this DocumentKit.

DocumentKit &UnsetJavaScript(char const *in_script_name)

Removes the script with a given name from the document.

Parameters: in_script_name – UTF8-encoded script name to remove from the document.
Returns: A reference to this DocumentKit.

DocumentKit &UnsetJavaScript(size_t in_count, UTF8 const in_script_names[])

Removes the scripts with the given names from the document.

Parameters

in_count – Size of the following array.
in_script_names – Script names to remove from the document.

Returns

A reference to this DocumentKit.

DocumentKit &UnsetJavaScript(UTF8Array const &in_script_names)

Removes the scripts with the given names from the document.

Parameters: in_script_names – Script names to remove from the document.
Returns: A reference to this DocumentKit.

DocumentKit &UnsetPage(size_t in_index)

Removes the page at the given index from the document.

Parameters: in_index – Index of the page to remove from the document.
Returns: A reference to this DocumentKit.

DocumentKit &UnsetPages()

Removes all pages from the document.

Returns: A reference to this DocumentKit.

DocumentKit &UnsetPages(size_t in_count, size_t const in_indices[])

Removes the pages at the given indices from the document.

Parameters

in_count – Size of the following array.
in_indices – Indices of the pages to remove from the document.

Returns

A reference to this DocumentKit.

DocumentKit &UnsetPages(SizeTArray const &in_indices)

Removes the pages at the given indices from the document.

Parameters: in_indices – Indices of the pages to remove from the document.
Returns: A reference to this DocumentKit.

DocumentKit &UnsetPasswords()

Removes the document passwords.

Returns: A reference to this DocumentKit.

DocumentKit &UnsetPermissions()

Removes permission settings from the document.

Returns: A reference to this DocumentKit.

Public Static Functions

static DocumentKit GetDefault()

Creates a DocumentKit which contains the default settings. The returned object will not necessarily have values for every setting, but it will have them where it is reasonable to have a default. These values will be used for export unless a setting is overridden by the DocumentKit passed to File::Export.

Returns: A DocumentKit with the default settings.