Apryse SDK

class apryse_sdk.ASCII85Encode(input_filter, line_width=72, buf_sz=256)

Bases: Filter

ASCII85Encode filter can be used to encode any data stream into a stream that does not contain any binary characters.

property thisown

The membership flag

class apryse_sdk.Action(args)

Bases: object

Actions are typically what happens when a user clicks on a link or bookmark.

Instead of simply jumping to a destination in the document, an annotation or outline item can specify an action for the viewer application to perform, such as launching an application, playing a sound, or changing an annotation’s appearance state.

Notes: Although the Action class provides utility functions for most commonly used action types, it is possible to read, write, and edit any action type using SDF API and dictionary entries described in Section 8.5 in the PDF Reference Manual.

static CreateGoto(args)

Overload 1:

Creates a new ‘GoTo’action. GoTo action takes the user to the specified Destination view located in the same document.

Parameters:

dest (Destination) – A Destination for the new Action.

Notes: This method can only be used for destinations in the same document as the source document. For cross-document links use Action::CreateGotoRemote().

Overload 2:

Creates a new ‘GoTo’ action using a ‘Named Destination’. GoTo action takes the user to the specified ‘Named Destination’ view located in the same document.

Parameters:

• key (UChar) –

  • a string buffer representing the destination name. The named

  destination will be stored in document’s ‘/Dest’ SDF::NameTree.

• key_sz (int) – The size in bytes of the key buffer.

• dest (Destination) – The explicit destination used to create the named destination.

static CreateGotoRemote(args)

Overload 1:

Creates a new ‘GoToR’action. A remote go-to action is similar to an ordinary go-to action but jumps to a destination in another PDF file instead of the current file.

Parameters:

• file (FileSpec) – The file referred to by the action.

• page_num (int) – A page number within the remote document. The first page is numbered 0. _window A flag specifying whether to open the destination document in a new window. If new_window is false, the destination document replaces the current document in the same window, otherwise the viewer application should behave in accordance with the current user preference.

Overload 2:

Creates a new ‘GoToR’action. See the above method for details.

Parameters:

• file (FileSpec) – The file referred to by the action.

• page_num (int) – A page number within the remote document. The first page is numbered 0.

• new_window (boolean) – A flag specifying whether to open the destination document in a new window. If new_window is false, the destination document replaces the current document in the same window, otherwise the viewer application should behave in accordance with the current user preference.

static CreateHideField(sdfdoc, field)

Creates a new ‘Show/Hide Field’ action. A show/hide field action shows or hide certain fields when it’s invoked.

Parameters:

• sdfdoc (SDFDoc) – the document in which to create the action

• list_length – the number of fields to hide

• field (std::vector< std::string,std::allocator< std::string > >) – the list of fields to hide

static CreateImportData(doc, path)

Creates a new ‘Import Data’ action. An import data action imports form data from a FDF file into a PDF document.

Parameters:

• doc (SDFDoc) – the document in which to create the action

• path (string) – the full path of the FDF file

static CreateInternal(impl)

static CreateJavaScript(doc, script)

Creates a new ‘JavaScript’ action. A javascript action executes a JavaScript script when it’s invoked.

Parameters:

• doc (SDFDoc) – the document in which to create the action

• script (string) – the JavaScript script to be executed

static CreateLaunch(doc, path)

Creates a new ‘Launch’ action. A launch action opens up a file using the most appropriate program.

Parameters:

• doc (SDFDoc) – the document in which to create the action

• path (string) – the full path of the file to be opened

static CreateResetForm(doc)

Creates a new ‘Reset Form’ action. A reset form action reset chosen form fields to their default value.

Parameters:

doc (SDFDoc) – the document in which to create the action

static CreateSubmitForm(url)

Creates a new ‘SubmitForm’action. A submit-form action transmits the names and values of selected interactive form fields to a specified uniform resource locator (URL), presumably the address of a Web server that will process them and send back a response.

Parameters:

url (FileSpec) – A URL file specification giving the uniform resource locator (URL) of the script at the Web server that will process the submission.

static CreateURI(args)

Overload 1:

Create a new URI action. The URI action is typically resolved by opening a URL in the default web browser.

Parameters:

• doc (SDFDoc) – The document in which to create the action.

• uri (string) – The uniform resource identifier to resolve, encoded in 7-bit ASCII. A uniform resource identifier (URI) is a string that identifies (resolves to) a resource on the Internet; typically a file that is the destination of a hypertext link, although it can also resolve to a query or other entity. (URIs are described in Internet RFC 2396, Uniform Resource Identifiers (URI).

Overload 2:

Create a new URI action. The URI action is typically resolved by opening a URL in the default web browser.

Parameters:

• doc (SDFDoc) – The document in which to create the action.

• uri (string) – The uniform resource identifier to resolve, encoded in UTF-8. A uniform resource identifier (URI) is a string that identifies (resolves to) a resource on the Internet; typically a file that is the destination of a hypertext link, although it can also resolve to a query or other entity. (URIs are described in Internet RFC 2396, Uniform Resource Identifiers (URI).

Execute()

Executes current action; this will only work for some action types that can be executed only using the information contained in the action object or the associated PDF doc. See also PDFViewCtrl::ExecuteAction()

ExecuteKeyStrokeAction(data)

Executes KeyStrokeAction, this shall be performed when the user modifies a character in a text field or combo box or modifies the selecton in a scrollable list box. This action checks the added text for validity and reject or modify it.

Parameters:

data (KeyStrokeEventData) – Data that contains previous text, added text,and added position information.

GetDest()

Return type:

Destination

Returns:

The Action’s Destination view.

Notes: This only works for Actions whose subtype is “GoTo”.

All named destinations are automatically resolved to the explicit destination so you can access destination members directly.

GetFormActionFlag(flag)

Parameters:

flag (int) – Action flag to get the value from.

Return type:

boolean

Returns:

boolean value of the given action flag.

Notes: Action flags are currently only used by submit and reset form actions.

GetHandleInternal()

GetNext()

Return type:

Obj

Returns:

The next action dictionary, an array of action dictionaries, or NULL if there are no additional actions.

Sequences of actions can be chained together. For example, the effect of clicking a link annotation with the mouse might be to play a sound, jump to a new page, and start up a movie. Note that the Next entry is not restricted to a single action but may contain an array of actions, each of which in turn may have a Next entry of its own. The actions may thus form a tree instead of a simple linked list. Actions within each Next array are executed in order, each followed in turn by any actions specified in its Next entry, and so on recursively.

GetSDFObj()

Return type:

Obj

Returns:

Pointer to the underlying SDF/Cos object.

GetType()

Return type:

int

Returns:

The type of this Action.

IsValid()

Indicates whether the Action is valid (non-null).

Return type:

boolean

Returns:

True if this is a valid (non-null) Action; otherwise false.

Notes: If this method returns false the underlying SDF/Cos object is null and the Action object should be treated as null as well.

NeedsWriteLock()

Test if the action needs writeLock

Return type:

boolean

Returns:

ture if needs, otherwise false

SetFormActionFlag(flag, value)

Set the value of a given field flag.

Parameters:

• flag (int) – Action flag to get the value from.

• value (boolean) – Boolean to set the value of the flag to. Action flags are currently only used by submit and reset form actions.

e_GoTo = 0

Go to a destination in the current document.

e_GoTo3DView = 17

(PDF 1.6) Set the current view of a 3D annotation

e_GoToE = 2

(‘Go-to embedded’; PDF 1.6) Go to a destination in an embedded file.

e_GoToR = 1

(‘Go-to remote’) Go to a destination in another document.

e_Hide = 8

Set an annotation’s Hidden flag.

e_ImportData = 12

Import field values from a file.

e_JavaScript = 13

Execute a JavaScript script.

e_Launch = 3

Launch an application, usually to open a file.

e_Movie = 7

Play a movie.

e_Named = 9

Execute an action predefined by the viewer application.

e_Rendition = 15

(PDF 1.5) Controls the playing of multimedia content.

e_ResetForm = 11

Set fields to their default values.

e_RichMediaExecute = 18

Adobe supplement to ISO 32000; specifies a command to be sent to rich media annotation’s handler

e_SetOCGState = 14

(PDF 1.5) Set the states of optional content groups.

e_Sound = 6

Play a sound.

e_SubmitForm = 10

Send data to a uniform resource locator.

e_Thread = 4

Begin reading an article thread.

e_Trans = 16

Updates the display of a document, using a transition dictionary.

e_URI = 5

Resolve a uniform resource identifier.

e_Unknown = 19

Unknown Action type

e_canonical_format = 9

e_embed_form = 13

e_excl_F_key = 11

e_excl_non_user_annots = 10

e_exclude = 0

e_export_format = 2

e_get_method = 3

e_include_annotations = 7

e_include_append_saves = 6

e_include_no_value_fields = 1

e_submit_coordinates = 4

e_submit_pdf = 8

e_xfdf = 5

property mp_action

property thisown

The membership flag

apryse_sdk.Action_CreateGoto(args)

Overload 1:

Creates a new ‘GoTo’action. GoTo action takes the user to the specified Destination view located in the same document.

Parameters:

dest (Destination) – A Destination for the new Action.

Notes: This method can only be used for destinations in the same document as the source document. For cross-document links use Action::CreateGotoRemote().

Overload 2:

Creates a new ‘GoTo’ action using a ‘Named Destination’. GoTo action takes the user to the specified ‘Named Destination’ view located in the same document.

Parameters:

• key (UChar) –

  • a string buffer representing the destination name. The named

  destination will be stored in document’s ‘/Dest’ SDF::NameTree.

• key_sz (int) – The size in bytes of the key buffer.

• dest (Destination) – The explicit destination used to create the named destination.

apryse_sdk.Action_CreateGotoRemote(args)

Overload 1:

Creates a new ‘GoToR’action. A remote go-to action is similar to an ordinary go-to action but jumps to a destination in another PDF file instead of the current file.

Parameters:

• file (FileSpec) – The file referred to by the action.

• page_num (int) – A page number within the remote document. The first page is numbered 0. _window A flag specifying whether to open the destination document in a new window. If new_window is false, the destination document replaces the current document in the same window, otherwise the viewer application should behave in accordance with the current user preference.

Overload 2:

Creates a new ‘GoToR’action. See the above method for details.

Parameters:

• file (FileSpec) – The file referred to by the action.

• page_num (int) – A page number within the remote document. The first page is numbered 0.

• new_window (boolean) – A flag specifying whether to open the destination document in a new window. If new_window is false, the destination document replaces the current document in the same window, otherwise the viewer application should behave in accordance with the current user preference.

apryse_sdk.Action_CreateHideField(sdfdoc, field)

Creates a new ‘Show/Hide Field’ action. A show/hide field action shows or hide certain fields when it’s invoked.

Parameters:

• sdfdoc (SDFDoc) – the document in which to create the action

• list_length – the number of fields to hide

• field (std::vector< std::string,std::allocator< std::string > >) – the list of fields to hide

apryse_sdk.Action_CreateImportData(doc, path)

Creates a new ‘Import Data’ action. An import data action imports form data from a FDF file into a PDF document.

Parameters:

• doc (SDFDoc) – the document in which to create the action

• path (string) – the full path of the FDF file

apryse_sdk.Action_CreateInternal(impl)

apryse_sdk.Action_CreateJavaScript(doc, script)

Creates a new ‘JavaScript’ action. A javascript action executes a JavaScript script when it’s invoked.

Parameters:

• doc (SDFDoc) – the document in which to create the action

• script (string) – the JavaScript script to be executed

apryse_sdk.Action_CreateLaunch(doc, path)

Creates a new ‘Launch’ action. A launch action opens up a file using the most appropriate program.

Parameters:

• doc (SDFDoc) – the document in which to create the action

• path (string) – the full path of the file to be opened

apryse_sdk.Action_CreateResetForm(doc)

Creates a new ‘Reset Form’ action. A reset form action reset chosen form fields to their default value.

Parameters:

doc (SDFDoc) – the document in which to create the action

apryse_sdk.Action_CreateSubmitForm(url)

Creates a new ‘SubmitForm’action. A submit-form action transmits the names and values of selected interactive form fields to a specified uniform resource locator (URL), presumably the address of a Web server that will process them and send back a response.

Parameters:

url (FileSpec) – A URL file specification giving the uniform resource locator (URL) of the script at the Web server that will process the submission.

apryse_sdk.Action_CreateURI(args)

Overload 1:

Create a new URI action. The URI action is typically resolved by opening a URL in the default web browser.

Parameters:

• doc (SDFDoc) – The document in which to create the action.

• uri (string) – The uniform resource identifier to resolve, encoded in 7-bit ASCII. A uniform resource identifier (URI) is a string that identifies (resolves to) a resource on the Internet; typically a file that is the destination of a hypertext link, although it can also resolve to a query or other entity. (URIs are described in Internet RFC 2396, Uniform Resource Identifiers (URI).

Overload 2:

Create a new URI action. The URI action is typically resolved by opening a URL in the default web browser.

Parameters:

• doc (SDFDoc) – The document in which to create the action.

• uri (string) – The uniform resource identifier to resolve, encoded in UTF-8. A uniform resource identifier (URI) is a string that identifies (resolves to) a resource on the Internet; typically a file that is the destination of a hypertext link, although it can also resolve to a query or other entity. (URIs are described in Internet RFC 2396, Uniform Resource Identifiers (URI).

class apryse_sdk.AdvancedImagingModule

Bases: object

The class AdvancedImagingModule. static interface to PDFTron SDKs AdvancedImaging functionality

static IsModuleAvailable()

Find out whether the AdvancedImaging module is available (and licensed).

Return type:

boolean

Returns:

returns true if AdvancedImaging operations can be performed.

property thisown

The membership flag

apryse_sdk.AdvancedImagingModule_IsModuleAvailable()

Find out whether the AdvancedImaging module is available (and licensed).

Return type:

boolean

Returns:

returns true if AdvancedImaging operations can be performed.

class apryse_sdk.Annot(args)

Bases: object

Annot is a base class for different types of annotations. For annotation specific properties, please refer to derived classes.

An annotation is an interactive object placed on a page, such as a text note, a link, or an embedded file. PDF includes a wide variety of standard annotation types. An annotation associates an object such as a widget, note, or movie with a location on a page of a PDF document, or provides a means of interacting with the user via the mouse and keyboard. For more details on PDF annotations please refer to section 12.5 in the PDF Reference Manual and the documentation in derived classes.

static Create(doc, type, pos)

Creates a new annotation of a given type, in the specified document. The newly created annotation does not contain any properties specific to a given annotation type, which means an invalid annotation object could be created. It is therefore recommended to always create an annotation using type specific methods, such as Annots::Line::Create() or Annots::FileAttachment::Create(). Users should only call Annot::Create() to create annotations of non-standard types that are not recognized by PDFTron software (by using Annot::e_Unknown as a type).

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• type (int) – Subtype of annotation to create.

• pos (Rect) – A rectangle specifying the annotation’s bounds, specified in user space coordinates.

Return type:

Annot

Returns:

A newly created blank annotation for the given annotation type.

static CreateInternal(impl)

DeleteCustomData(key)

Deletes custom data associated with the given key.

Parameters:

key (string) – The key for which to delete the associated data.

Flatten(page)

Flatten/Merge the existing annotation appearances with the page content and delete this annotation from a given page.

Annotation ‘flattening’ refers to the operation that changes active annotations (such as markup, widgets, 3D models, etc.) into a static area that is part of the PDF document, just like the other text and images in the document.

Notes: an alternative approach to set the annotation as read only is using Annot.SetFlag(Annot::e_read_only, true) method. Unlike Annot.SetFlag(…), the result of Flatten() operation can not be programatically reversed.

GetActiveAppearanceState()

Gets the annotation’s active appearance state.

Return type:

string

Returns:

the name of the active state. The annotation’s appearance state, which selects the applicable appearance stream from an appearance subdictionary.

GetAppearance(args)

Gets the annotation’s appearance for the given combination of annotation and appearance states.

Parameters:

• annot_state (int) – the annotation’s appearance state, which selects the applicable appearance stream from the appearance sub-dictionary. An annotation can define as many as three separate appearances: The normal, rollover, and down appearance.

• app_state (string) – is an optional parameter specifying the appearance state to look for (e.g. “Off”, “On”, etc). If appearance_state is NULL, the choice between different appearance states is determined by the AS (Appearance State) entry in the annotation dictionary.

Return type:

Obj

Returns:

The appearance stream for this annotation, or NULL if the annotation does not have an appearance for the given combination of annotation and appearance states.

GetBorderStyle()

Gets the border style for the annotation. Typically used for Link annotations.

Return type:

BorderStyle

Returns:

Annotation’s border style.

GetColorAsCMYK()

Returns the annotation’s color in CMYK color space.

Return type:

ColorPt

Returns:

A ColorPt object containing an array of four numbers in the range 0.0 to 1.0, representing a CMYK color used for the following purposes:

• The background of the annotation’s icon when closed

• The title bar of the annotation’s pop-up window

• The border of a link annotation

If the annotation does not specify an explicit color, a default color is returned. Text annotations return ‘default yellow;’ all others return black.

GetColorAsGray()

Returns the annotation’s color in Gray color space.

Return type:

ColorPt

Returns:

A ColorPt object containing a number in the range 0.0 to 1.0, representing a Gray Scale color used for the following purposes: The background of the annotation’s icon when closed The title bar of the annotation’s pop-up window The border of a link annotation If the annotation does not specify an explicit color, black color is returned.

GetColorAsRGB()

Gets an annotation’s color in RGB color space.

Return type:

ColorPt

Returns:

A ColorPt object containing an array of three numbers in the range 0.0 to 1.0,

representing an RGB colour used for the following purposes:

• The background of the annotation’s icon when closed

• The title bar of the annotation’s pop-up window

• The border of a link annotation

If the annotation does not specify an explicit color, a default color is returned. Text annotations return ‘default yellow;’ all others return black.

GetColorCompNum()

Returns the color space the annotation’s color is represented in.

Return type:

int

Returns:

An integer that is either 1(for DeviceGray), 3(DeviceRGB), or 4(DeviceCMYK). If the annotation has no color, i.e. is transparent, 0 will be returned.

GetContents()

Extract the content of this annotation. (Optional).

Return type:

string

Returns:

A unicode string object with the text that is associated with this annotation. This is the text that annotation displays on user interaction, if the annotation type supports it.

GetCustomData(key)

Returns custom data associated with the given key.

Parameters:

key (string) – The key for which to retrieve the associated data.

Return type:

string

Returns:

the custom data string. If no data is available an empty string is returned.

GetDate()

Gets an annotation’s last modified date.

Return type:

Date

Returns:

The annotation’s last modified time and date. If the annotation has no associated date structure, the returned date is not valid (date.IsValid() returns false). Corresponds to the “M” entry of the annotation dictionary.

GetFlag(flag)

Return type:

boolean

Returns:

The value of given Flag

Parameters:

flag (int) – The Flag property to query.

GetHandleInternal()

GetOptionalContent()

Returns optional content associated with this annotation.

Return type:

Obj

Returns:

A SDF object corresponding to the group of optional properties.

Notes: The return value is an Optional Content Group (OCG) or Optional Content Membership Dictionary (PDF::OCG::OCMD) specifying the optional content properties for the annotation. Before the annotation is drawn, its visibility shall be determined based on this entry as well as the annotation flags specified in the Flag entry. If it is determined to be invisible, the annotation shall be skipped, as if it were not in the document.

GetPage()

Gets the page the annotation is associated with.

Return type:

Page

Returns:

A Page object or null page object if the page reference is not available. The page object returned is an indirect reference to the page object with which this annotation is associated. This entry shall be present in screen annotations associated with rendition actions.

Optional. PDF 1.3 PDF 1.4 PDF 1.5 not used in FDF files.

GetRect()

Return type:

Rect

Returns:

Annotation’s bounding rectangle, specified in user space coordinates.

The meaning of the rectangle depends on the annotation type. For Link and RubberStamp annotations, the rectangle specifies the area containing the hyperlink area or stamp. For Note annotations, the rectangle is describing the popup window when it’s opened. When it’s closed, the icon is positioned at lower left corner.

GetRotation()

Returns the rotation value of the annotation. The Rotation specifies the number of degrees by which the annotation shall be rotated counterclockwise relative to the page. The value shall be a multiple of 90.

Return type:

int

Returns:

An integer representing the rotation value of the annotation.

Notes: This property is part of the appearance characteristics dictionary, this dictionary that shall be used inructing a dynamic appearance stream specifying the annotation’s visual presentation on the page.

GetSDFObj()

Return type:

Obj

Returns:

The underlying SDF/Cos object.

GetStructParent()

Returns the struct parent of an annotation. (Required if the annotation is a structural content item; PDF 1.3)

Return type:

int

Returns:

An integer which is the integer key of the annotation’s entry in the structural parent tree.

Notes: The StructParent is the integer key of the annotation’s entry in the structural parent tree.

GetTriggerAction(trigger)

Get the Action associated with the selected Annot Trigger event.

Parameters:

trigger (int) – the type of trigger event to get

Return type:

Obj

Returns:

the Action Obj if present, otherwise NULL

GetType()

Return type:

int

Returns:

The type of this annotation. Corresponds to the “Subtype” entry of annotation dictionary, as per PDF Reference Manual section 12.5.2

GetUniqueID()

Return type:

Obj

Returns:

The unique identifier for this annotation, or NULL if the identifier is not available. The returned value is a String object and is the value of the “NM” field, which was added as an optional attribute in PDF 1.4.

GetVisibleContentBox()

It is possible during viewing that GetRect does not return the most accurate bounding box of what is actually rendered. This method calculates the bounding box, rather than relying on what is specified in the PDF document. The bounding box is defined as the smallest rectangle that includes all the visible content on the annotation.

Return type:

Rect

Returns:

the bounding box for this annotation. The dimensions are specified in user space coordinates.

IsMarkup()

Return true if this annotation is classified as a markup annotation.

Return type:

boolean

Returns:

boolean value, true if this annotation is classified as a markup annotation.

IsValid()

Return type:

boolean

Returns:

True if this is a valid (non-null) annotation, false otherwise. If the function returns false the underlying SDF/Cos object is null or is not valid and the annotation object should be treated as a null object.

RefreshAppearance(args)

Overload 1:

Regenerates the appearance stream for the annotation. This method can be used to auto-generate the annotation appearance after creating or modifying the annotation without providing an explicit appearance or setting the “NeedAppearances” flag in the AcroForm dictionary.

Notes: If this annotation contains text, and has been added to a rotated page, the text in the annotation may be rotated. If RefreshAppearance is called after the annotation is added to a rotated page, then any text will be rotated in the opposite direction of the page rotation. If this method is called before the annotation is added to any rotated page, then no counter rotation will be applied. If you wish to call RefreshAppearance on an annotation already added to a rotated page, but you don’t want the text to be rotated, you can do one of the following; temporarily un-rotate the page, or, temporarily remove the “Rotate” object from the annotation. To support users adding text annotations while using a PDF viewer, you can also add any viewer rotation to the annotations Rotate object, to have text always rotated correctly, from the users perspective.

Overload 2:

A version of RefreshAppearance allowing custom options to make slight tweaks in behaviour.

Parameters:

options (RefreshOptions) – The RefreshOptions.

RemoveAppearance(args)

Removes the annotation’s appearance for the given combination of annotation and appearance states.

Parameters:

• annot_state (int) – the annotation’s appearance state, which selects the applicable appearance stream from the appearance sub-dictionary. An annotation can define as many as three separate appearances: The normal, rollover, and down appearance.

• app_state (string) – is an optional parameter specifying the appearance state (e.g. “Off”, “On”, etc) under which the new appearance should be stored. If appearance_state is NULL, the annotation will have only one annotation state.

Resize(newrect)

Scales the geometry of the annotation so that its appearance would now fit a new rectangle on the page, in user units. Users still have to call RefreshAppearance() later if they want a corresponding appearance stream to be generated for the new rectangle. The main reason for not combining the two operations together is to be able to resize annotations that do not have an appearance stream.

Parameters:

newrect (Rect) – A reference to the new rectangle to which this annotation has to be resized.

SetActiveAppearanceState(astate)

Sets the annotation’s active appearance state. (Required if the appearance dictionary AP contains one or more subdictionaries; PDF 1.2)

Parameters:

astate (string) – Character string representing the name of the active appearance state. The string used to select the annotation’s appearance state, which selects the applicable appearance stream from an appearance subdictionary.

SetAppearance(args)

Sets the annotation’s appearance for the given combination of annotation and appearance states. (Optional; PDF 1.2)

Parameters:

• app_stream (Obj) – a content stream defining the new appearance.

• annot_state (int) – the annotation’s appearance state, which selects the applicable appearance stream from the appearance sub-dictionary. An annotation can define as many as three separate appearances: The normal, rollover, and down appearance.

• app_state (string) – is an optional parameter specifying the appearance state (e.g. “Off”, “On”, etc) under which the new appearance should be stored. If appearance_state is NULL, the annotation will have only one annotation state.

SetBorderStyle(bs, oldStyleOnly=False)

Sets the border style for the annotation.

Parameters:

• bs (BorderStyle) – New border style for this annotation.

• oldStyleOnly (boolean) – PDF manual specifies two ways to add border information to an annotation object, either through an array named ‘Border’ (PDF 1.0), or a dictionary called ‘BS’ (PDF 1.2) the latter taking precedence over the former. However, if you want to create a border with rounded corners, you can only do that using PDF 1.0 Border specification, in which case if you call SetBorderStyle() set the parameter oldStyleOnly to true. This parameter has a default value of false in the API and does not need to be used otherwise.

SetColor(col, numcomp=3)

Sets an annotation’s color. (Optional; PDF 1.1)

Parameters:

col (ColorPt) –

A ColorPt object in RGB or Gray or CMYK color space representing the annotation’s color. The ColorPt contains an array of numbers in the range 0.0 to 1.0, representing a color used for the following purposes:

The background of the annotation’s icon when closed

The title bar of the annotation’s pop-up window The border of a link annotation

The number of array elements determines the color space in which the color shall be defined: 0 No color; transparent 1 DeviceGray 3 DeviceRGB 4 DeviceCMYK

Parameters:

numcomp (int) –

• The number of color components used to represent the color (i.e. 1, 3, 4).

SetContents(contents)

Sets the content of this annotation. (Optional).

Parameters:

contents (string) – A reference to unicode string object with the text that will be associated with this annotation. This is the text that annotation displays on user interaction, if the annotation type supports it.

SetCustomData(key, value)

Sets the custom data associated with the specified key.

Parameters:

• key (string) – The key under which to store this custom data

• value (string) – The custom data string to store

SetDate(date)

Sets an annotation’s last modified date.

Parameters:

date (Date) – The annotation’s last modified time and date. Corresponds to the “M” entry of the annotation dictionary.

SetFlag(flag, value)

Sets the value of given Flag.

Parameters:

• flag (int) – The Flag property to modify.

• value (boolean) – The new value for the property.

SetOptionalContent(content)

Associates optional content with this annotation. (Optional, PDF1.5).

Parameters:

content (Obj) – A pointer to an SDF object corresponding to the optional content, a PDF::OCG::Group or membership dictionary specifying the PDF::OCG::Group properties for the annotation. Before the annotation is drawn, its visibility shall be determined based on this entry as well as the annotation flags specified in the Flag entry . If it is determined to be invisible, the annotation shall be skipped, as if it were not in the document.

SetPage(page)

Sets the reference to a page the annotation is associated with. (Optional PDF 1.3; not used in FDF files)

Parameters:

page (Page) – The page object user wants the annotation to be associated with.

Notes: The parameter should be an indirect reference to the page object with which this annotation is associated. This entry shall be present in screen annotations associated with rendition actions

SetRect(pos)

Sets the size and location of an annotation on its page.

Parameters:

pos (Rect) – Annotation’s bounding rectangle, specified in user space coordinates.

The meaning of the rectangle depends on the annotation type. For Link and RubberStamp annotations, the rectangle specifies the area containing the hyperlink area or stamp. For Note annotations, the rectangle is describing the popup window when it’s opened. When it’s closed, the icon is positioned at lower left corner.

SetRotation(angle)

Sets the rotation value of the annotation. The Rotation specifies the number of degrees by which the annotation shall be rotated counterclockwise relative to the page. The value shall be a multiple of 90. (Optional)

Parameters:

angle (int) – An integer representing the rotation value of the annotation.

Notes: This property is part of the appearance characteristics dictionary, this dictionary that shall be used inructing a dynamic appearance stream specifying the annotation’s visual presentation on the page.

SetStructParent(parkeyval)

Sets the struct parent of an annotation. (Required if the annotation is a structural content item; PDF 1.3)

Parameters:

parkeyval (int) – An integer which is the integer key of the annotation’s entry in the structural parent tree.

Notes: The StructParent is the integer key of the annotation’s entry in the structural parent tree.

SetUniqueID(id, id_buf_sz=0)

Sets the unique identifier for this annotation.

Parameters:

• id (string) – A buffer containing a unique identifier for this annotation.

• id_buf_sz (int) – The size of ‘id’ buffer, or 0 if the string is NULL terminated.

Notes: It is necessary to ensure that the unique ID generated is actually unique.

e_3D = 24

3D annotation

e_Caret = 13

Caret annotation

e_Circle = 5

Circle annotation

e_FileAttachment = 16

File attachment annotation

e_FreeText = 2

Free text annotation

e_Highlight = 8

Highlight annotation

e_Ink = 14

Ink annotation

e_Line = 3

Line annotation

e_Link = 1

Link annotation

e_Movie = 18

Movie annotation

e_Polygon = 6

Polygon annotation

e_Polyline = 7

Polyline annotation

e_Popup = 15

Pop-up annotation

e_PrinterMark = 21

Printer’s mark annotation

e_Projection = 26

Projection annotation, Adobe supplement to ISO 32000

e_Redact = 25

Redact annotation

e_RichMedia = 27

Rich Media annotation, Adobe supplement to ISO 32000

e_Screen = 20

Screen annotation

e_Sound = 17

Sound annotation

e_Square = 4

Square annotation

e_Squiggly = 10

Squiggly-underline annotation

e_Stamp = 12

Rubber stamp annotation

e_StrikeOut = 11

Strikeout annotation

e_Text = 0

Text annotation

e_TrapNet = 22

Trap network annotation

e_Underline = 9

Underline annotation

e_Unknown = 28

Any other annotation type, not listed in PDF spec and unrecognized by PDFTron software

e_Watermark = 23

Watermark annotation

e_Widget = 19

Widget annotation

e_action_trigger_activate = 0

e_action_trigger_annot_blur = 6

e_action_trigger_annot_down = 3

e_action_trigger_annot_enter = 1

e_action_trigger_annot_exit = 2

e_action_trigger_annot_focus = 5

e_action_trigger_annot_page_close = 8

e_action_trigger_annot_page_invisible = 10

e_action_trigger_annot_page_open = 7

e_action_trigger_annot_page_visible = 9

e_action_trigger_annot_up = 4

e_down = 2

e_hidden = 1

e_invisible = 0

e_locked = 7

e_locked_contents = 9

e_no_rotate = 4

e_no_view = 5

e_no_zoom = 3

e_normal = 0

e_print = 2

e_read_only = 6

e_rollover = 1

e_toggle_no_view = 8

property mp_annot

property thisown

The membership flag

apryse_sdk.Annot_Create(doc, type, pos)

Creates a new annotation of a given type, in the specified document. The newly created annotation does not contain any properties specific to a given annotation type, which means an invalid annotation object could be created. It is therefore recommended to always create an annotation using type specific methods, such as Annots::Line::Create() or Annots::FileAttachment::Create(). Users should only call Annot::Create() to create annotations of non-standard types that are not recognized by PDFTron software (by using Annot::e_Unknown as a type).

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• type (int) – Subtype of annotation to create.

• pos (Rect) – A rectangle specifying the annotation’s bounds, specified in user space coordinates.

Return type:

Annot

Returns:

A newly created blank annotation for the given annotation type.

apryse_sdk.Annot_CreateInternal(impl)

class apryse_sdk.Appearance

Bases: object

Class used to customize the appearance of the optional redaction overlay.

property Border

Border specifies if the overlay will be surrounded by a border.

property HorizTextAlignment

Specifies the horizontal text alignment in the overlay: align<0 -> text will be left aligned. align==0 -> text will be center aligned. align>0 -> text will be right aligned.

property MaxFontSize

property MinFontSize

Specifies the minimum and maximum font size used to represent the text in the overlay.

property NegativeOverlayColor

NegativeOverlayColor defines the overlay background color in RGB color space for negative redactions.

property PositiveOverlayColor

PositiveOverlayColor defines the overlay background color in RGB color space for positive redactions.

property RedactedContentColor

Specifies the color used to paint the regions where content was removed. Only useful when ShowRedactedContentRegions == true. Default value is Gray color.

property RedactionOverlay

If RedactionOverlay is set to true, Redactor will draw an overlay covering all redacted regions. The rest of properties in the Appearance class defines visual properties of the overlay. If false the overlay region will not be drawn.

property ShowRedactedContentRegions

Specifies whether an overlay should be drawn in place of the redacted content. This option can be used to indicate the areas where the content was removed from without revealing the content itself. Default value is False. Notes: The overlay region used RedactedContentColor as a fill color.

property TextColor

Specifies the color used to paint the text in the overlay (in RGB).

property TextFont

Specifies the font used to represent the text in the overlay.

property UseOverlayText

Specifies if the text (e.g. “Redacted” etc.) should be placed on top of the overlay. The remaining properties relate to the positioning, and styling of the overlay text.

property VertTextAlignment

Specifies the vertical text alignment in the overlay: align<0 -> text will be top aligned. align==0 -> text will be center aligned. align>0 -> text will be bottom aligned.

property thisown

The membership flag

class apryse_sdk.AttrObj(args)

Bases: object

An application or plug-in extension that processes logical structure can attach additional information, called attributes, to any structure element. The attribute information is held in one or more attribute objects associated with the structure element. An attribute object is a dictionary or stream that includes an entry identifying the application or plug-in that owns the attribute information. Other entries represent the attributes: the keys are attribute names, and values are the corresponding attribute values.

GetOwner()

Return type:

string

Returns:

The name of the application or plug-in extension owning the attribute data.

GetSDFObj()

Return type:

Obj

Returns:

Pointer to the underlying SDF/Cos object.

property thisown

The membership flag

class apryse_sdk.BitmapInfo(args)

Bases: object

GetBuffer()

property dpi

property height

property stride

property thisown

The membership flag

property width

class apryse_sdk.Bookmark(args)

Bases: object

A %PDF document may optionally display a document outline on the screen, allowing the user to navigate interactively from one part of the document to another. The outline consists of a tree-structured hierarchy of Bookmarks (sometimes called outline items), which serve as a ‘visual table of contents’ to display the document’s structure to the user.

Each Bookmark has a title that appears on screen, and an Action that specifies what happens when a user clicks on the Bookmark. The typical action for a user-created Bookmark is to move to another location in the current document, although any action (see PDF::Action) can be specified.

Bookmark is a utility class used to simplify work with %PDF bookmarks (or outlines; see section 8.2.2 ‘Document Outline’ in %PDF Reference Manual for more details).

AddChild(args)

Overload 1:

Adds a new Bookmark as the new last child of this Bookmark.

Parameters:

in_title (string) – The title string value of the new Bookmark.

Return type:

Bookmark

Returns:

The newly created child Bookmark.

Notes: If this Bookmark previously had no children, it will be open after the child is added.

Overload 2:

Adds the specified Bookmark as the new last child of this Bookmark.

Parameters:

in_bookmark (Bookmark) – The Bookmark object to be added as a last child of this Bookmark.

Notes: Parameter in_bookmark must not be linked to a bookmark tree. If this Bookmark previously had no children, it will be open after the child is added.

AddNext(args)

Overload 1:

Adds a new Bookmark to the tree containing this Bookmark, as the new right sibling.

Parameters:

in_title (string) – The title string value of the new Bookmark.

Return type:

Bookmark

Returns:

The newly created sibling Bookmark.

Overload 2:

Adds the specified Bookmark as the new right sibling to this Bookmark, adjusting the tree containing this Bookmark appropriately.

Parameters:

in_bookmark (Bookmark) – The Bookmark object to be added to this Bookmark.

Notes: Parameter in_bookmark must not be linked to a bookmark tree.

AddPrev(args)

Overload 1:

Adds a new Bookmark to the tree containing this Bookmark, as the new left sibling.

Parameters:

in_title (string) – The title string value of the new Bookmark.

Return type:

Bookmark

Returns:

The newly created sibling Bookmark.

Overload 2:

Adds the specified Bookmark as the new left sibling to this Bookmark, adjusting the tree containing this Bookmark appropriately.

Parameters:

in_bookmark (Bookmark) – The Bookmark object to be added to this Bookmark.

Notes: Parameter in_bookmark must not be linked to a bookmark tree.

static Create(in_doc, in_title)

Creates a new valid Bookmark with given title in the specified document.

Parameters:

• in_doc (PDFDoc) – The document in which a Bookmark is to be created.

• in_title (string) – The title string value of the new Bookmark.

Return type:

Bookmark

Returns:

The new Bookmark.

Notes: The new Bookmark is not linked to the outline tree. Use AddChild()/AddNext()/AddPrev() methods in order to link the Bookmark to the outline tree

static CreateInternal(impl)

Delete()

Removes the Bookmark’s subtree from the bookmark tree containing it.

Find(in_title)

Returns the Bookmark specified by the given title string.

Parameters:

in_title (string) – The title string value of the Bookmark to find.

Return type:

Bookmark

Returns:

A Bookmark matching the title string value specified.

GetAction()

Returns the Bookmark’s action.

Return type:

Action

Returns:

The Bookmark’s action.

GetColor()

Returns the Bookmark’s RGB color value.

Parameters:

• out_r – Reference to a variable that receives the red component of the color.

• out_g – Reference to a variable that receives the green component of the color.

• out_b – Reference to a variable that receives the blue component of the color.

Notes: The three numbers out_r, out_g, and out_b are in the range 0.0 to 1.0, representing the components in the DeviceRGB color space of the color to be used for the Bookmark’s text.

Example:

double red, green, blue;
bookmark.GetColor(red, green, blue);

GetFirstChild()

Returns the Bookmark’s first child.

Return type:

Bookmark

Returns:

The Bookmark’s first child.

GetFlags()

Returns the Bookmark’s flags.

Return type:

int

Returns:

The flags of the Bookmark object. Bit 1 (least-significant bit) indicates italic font whereas bit 2 indicates bold font. Therefore, 0 indicates normal, 1 is italic, 2 is bold, and 3 is bold-italic.

GetHandleInternal()

GetIndent()

Returns the indentation level of the Bookmark in its containing tree.

Return type:

int

Returns:

The indentation level of the Bookmark in its containing tree.

Notes: The root level has an indentation level of zero.

GetLastChild()

Returns the Bookmark’s last child.

Return type:

Bookmark

Returns:

The Bookmark’s last child.

GetNext()

Returns the Bookmark’s next (right) sibling.

Return type:

Bookmark

Returns:

the Bookmark’s next (right) sibling.

GetOpenCount()

Returns the number of opened bookmarks in this subtree.

Return type:

int

Returns:

The number of opened bookmarks in this subtree (not including this Bookmark). If the item is closed, a negative integer whose absolute value specifies how many descendants would appear if the item were reopened.

GetParent()

Returns the Bookmark’s parent Bookmark.

Return type:

Bookmark

Returns:

The Bookmark’s parent Bookmark.

GetPrev()

Returns the Bookmark’s previous (left) sibling.

Return type:

Bookmark

Returns:

The Bookmark’s previous (left) sibling.

GetSDFObj()

Returns the underlying SDF/Cos object.

Return type:

Obj

Returns:

The underlying SDF/Cos object.

Notes: A null (non-valid) bookmark returns a null object.

GetTitle()

Returns the Bookmark’s title string.

Return type:

string

Returns:

The Bookmark’s title string).

GetTitleObj()

Returns the Bookmark’s title string object.

Return type:

Obj

Returns:

The Bookmark’s title string object.

HasChildren()

Indicates whether the Bookmark has children.

Return type:

boolean

Returns:

True if the Bookmark has children; otherwise false.

IsOpen()

Indicates whether the Bookmark is open.

Return type:

boolean

Returns:

True if this Bookmark is open; otherwise false.

Notes: An open Bookmark shows all its children.

IsValid()

Indicates whether the Bookmark is valid (non-null).

Return type:

boolean

Returns:

True if this is a valid (non-null) Bookmark; otherwise false.

Notes: If this method returns false the underlying SDF/Cos object is null and the Bookmark object should be treated as null as well.

RemoveAction()

Removes the Bookmark’s action.

SetAction(in_action)

Sets the Bookmark’s action.

Parameters:

in_action (Action) – The new Action for the Bookmark.

SetColor(in_r=0.0, in_g=0.0, in_b=0.0)

Sets the Bookmark’s color value.

Parameters:

• in_r (double) – The red component of the color.

• in_g (double) – The green component of the color.

• in_b (double) – The blue component of the color.

Notes: The three numbers in_r, in_g, and in_b are in the range 0.0 to 1.0, representing the components in the DeviceRGB color space of the color to be used for the Bookmark’s text. Default color value is black, [0.0 0.0 0.0].

SetFlags(in_flags)

Sets the Bookmark’s flags.

Parameters:

in_flags (int) – The new bookmark flags. Bit 1 (the least-significant bit) indicates italic font whereas bit 2 indicates bold font. Therefore, 0 indicates normal, 1 is italic, 2 is bold, and 3 is bold-italic.

SetOpen(in_open)

Opens or closes the Bookmark.

Parameters:

in_open (boolean) – Boolean value that contains the status. If true, the Bookmark is opened. Otherwise the Bookmark is closed.

Notes: An opened Bookmark shows its children, while a closed Bookmark does not.

SetTitle(title)

Sets the Bookmark’s title string.

Parameters:

title (string) – The new title string for the bookmark.

Unlink()

Unlinks this Bookmark from the bookmark tree that contains it, and adjusts the tree appropriately.

Notes: After the bookmark is unlinked is can be moved to another place in the bookmark tree located in the same document.

property mp_obj

property thisown

The membership flag

apryse_sdk.Bookmark_Create(in_doc, in_title)

Creates a new valid Bookmark with given title in the specified document.

Parameters:

• in_doc (PDFDoc) – The document in which a Bookmark is to be created.

• in_title (string) – The title string value of the new Bookmark.

Return type:

Bookmark

Returns:

The new Bookmark.

Notes: The new Bookmark is not linked to the outline tree. Use AddChild()/AddNext()/AddPrev() methods in order to link the Bookmark to the outline tree

apryse_sdk.Bookmark_CreateInternal(impl)

class apryse_sdk.BorderStyle(args)

Bases: object

BorderStyle structure specifies the characteristics of the annotation’s border. The border is specified as a rounded rectangle.

Destroy()

Frees the native memory of the object.

GetDash()

Return type:

std::vector< double,std::allocator< double > >

Returns:

the border dash pattern.

See also: BorderStyle()

GetHR()

Return type:

double

Returns:

horizontal corner radius.

GetStyle()

Return type:

int

Returns:

the border style.

GetVR()

Return type:

double

Returns:

vertical corner radius.

GetWidth()

Return type:

double

Returns:

the border width.

SetDash(dash)

Sets the border dash pattern. See also: BorderStyle()

SetHR(horizontal_radius)

Sets horizontal corner radius.

Parameters:

horizontal_radius (double) – A number representing the value of the horizontal radius to set the annotation to.

SetStyle(style)

Sets the border style.

SetVR(vertical_radius)

Sets vertical corner radius.

Parameters:

vertical_radius (double) – A number representing the value of the vertical radius to set the annotation to.

SetWidth(width)

Sets the border width

Parameters:

width (double) – A number representing the width value to set the annotation to.

e_beveled = 2

A simulated embossed rectangle that appears to be raised above the surface of the page.

e_dashed = 1

A dashed rectangle surrounding the annotation.

e_inset = 3

A simulated engraved rectangle that appears to be recessed below the surface of the page.

e_solid = 0

A solid rectangle surrounding the annotation.

e_underline = 4

A single line along the bottom of the annotation rectangle.

property thisown

The membership flag

class apryse_sdk.CADConvertOptions

Bases: object

AddSheets(value)

Adds the Sheets to the Sheets array The list of sheets to be converted – only applies to .rvt conversions

Parameters:

value: – the new Sheets to be added to Sheets

Return type:

CADConvertOptions

Returns:

this object, for call chaining

GetAllowThinLines()

Gets the value AllowThinLines from the options object Sets drawing line weights to zero

Return type:

boolean

Returns:

a bool, the current value for AllowThinLines.

GetAutoRotate()

Gets the value AutoRotate from the options object Maps the orientation to the sheet dimensions

Return type:

boolean

Returns:

a bool, the current value for AutoRotate.

GetBackgroundColor()

Gets the value BackgroundColor from the options object Sets background color for cad conversion (display palette may be adjusted to contrast the chosen background color)

Return type:

ColorPt

Returns:

a ColorPt, the current value for BackgroundColor.

GetColorMode()

Gets the value ColorMode from the options object Sets the color palette used by the drawing export. Possible values are Mono (i.e., monochrome) and Gray (i.e., grayscale), otherwise drawing’s original palette is used

Return type:

string

Returns:

a string, the current value for ColorMode.

GetIncludeModel()

Gets the value IncludeModel from the options object Instructs the conversion process to include the model layout (default: true). Note that if the model layout is empty, it will never be included in the output

Return type:

boolean

Returns:

a bool, the current value for IncludeModel.

GetInternalObj(args)

GetLayoutSortOrder()

Gets the value LayoutSortOrder from the options object Specifies how the layout is sorted during cad to pdf conversion. This affects how each layout is inserted into the output pdf (each layout becomes a pdf page).

Return type:

int

Returns:

a LayoutSortOrder, the current value for LayoutSortOrder.

GetMaxXrefDepth()

Gets the value MaxXrefDepth from the options object Maximum resolution depth for nested xrefs. Root drawing starts at level 0, subsequent nested levels increment by 1. Nested xrefs at levels greater than specified will not be loaded.

Return type:

int

Returns:

a UInt32, the current value for MaxXrefDepth.

GetPageHeight()

Gets the value PageHeight from the options object The height of the output pdf, in millimeters

Return type:

double

Returns:

a double, the current value for PageHeight.

GetPageWidth()

Gets the value PageWidth from the options object The width of the output pdf, in millimeters

Return type:

double

Returns:

a double, the current value for PageWidth.

GetRasterDPI()

Gets the value RasterDPI from the options object Rasterization dpi used when rendering 3D content. Currently only applies to .rvt conversions

Return type:

double

Returns:

a double, the current value for RasterDPI.

GetUseScaleFromDocument()

Gets the value UseScaleFromDocument from the options object If enabled, sets export paper size equal to layout geometry’s coordinate range in mm when ranges are less than 5080 mm. Paper size dimensions are clamped at 5080 mm, and are rescaled if coordinate ranges exceed 5080 mm. Disabled by default.

Return type:

boolean

Returns:

a bool, the current value for UseScaleFromDocument.

GetZoomToExtents()

Gets the value ZoomToExtents from the options object If enabled, the layout geometry is zoomed to the paper size, otherwise layout settings are applied. Enabled by default.

Return type:

boolean

Returns:

a bool, the current value for ZoomToExtents.

SetAllowThinLines(value)

Sets the value for AllowThinLines in the options object Sets drawing line weights to zero

Parameters:

value: – the new value for AllowThinLines

Return type:

CADConvertOptions

Returns:

this object, for call chaining

SetAutoRotate(value)

Sets the value for AutoRotate in the options object Maps the orientation to the sheet dimensions

Parameters:

value: – the new value for AutoRotate

Return type:

CADConvertOptions

Returns:

this object, for call chaining

SetBackgroundColor(value)

Sets the value for BackgroundColor in the options object Sets background color for cad conversion (display palette may be adjusted to contrast the chosen background color)

Parameters:

value: – the new value for BackgroundColor

Return type:

CADConvertOptions

Returns:

this object, for call chaining

SetColorMode(value)

Sets the value for ColorMode in the options object Sets the color palette used by the drawing export. Possible values are Mono (i.e., monochrome) and Gray (i.e., grayscale), otherwise drawing’s original palette is used

Parameters:

value: – the new value for ColorMode

Return type:

CADConvertOptions

Returns:

this object, for call chaining

SetIncludeModel(value)

Sets the value for IncludeModel in the options object Instructs the conversion process to include the model layout (default: true). Note that if the model layout is empty, it will never be included in the output

Parameters:

value: – the new value for IncludeModel

Return type:

CADConvertOptions

Returns:

this object, for call chaining

SetLayoutSortOrder(value)

Sets the value for LayoutSortOrder in the options object Specifies how the layout is sorted during cad to pdf conversion. This affects how each layout is inserted into the output pdf (each layout becomes a pdf page).

Parameters:

value: – the new value for LayoutSortOrder

Return type:

CADConvertOptions

Returns:

this object, for call chaining

SetMaxXrefDepth(value)

Sets the value for MaxXrefDepth in the options object Maximum resolution depth for nested xrefs. Root drawing starts at level 0, subsequent nested levels increment by 1. Nested xrefs at levels greater than specified will not be loaded.

Parameters:

value: – the new value for MaxXrefDepth

Return type:

CADConvertOptions

Returns:

this object, for call chaining

SetPageHeight(value)

Sets the value for PageHeight in the options object The height of the output pdf, in millimeters

Parameters:

value: – the new value for PageHeight

Return type:

CADConvertOptions

Returns:

this object, for call chaining

SetPageWidth(value)

Sets the value for PageWidth in the options object The width of the output pdf, in millimeters

Parameters:

value: – the new value for PageWidth

Return type:

CADConvertOptions

Returns:

this object, for call chaining

SetRasterDPI(value)

Sets the value for RasterDPI in the options object Rasterization dpi used when rendering 3D content. Currently only applies to .rvt conversions

Parameters:

value: – the new value for RasterDPI

Return type:

CADConvertOptions

Returns:

this object, for call chaining

SetUseScaleFromDocument(value)

Sets the value for UseScaleFromDocument in the options object If enabled, sets export paper size equal to layout geometry’s coordinate range in mm when ranges are less than 5080 mm. Paper size dimensions are clamped at 5080 mm, and are rescaled if coordinate ranges exceed 5080 mm. Disabled by default.

Parameters:

value: – the new value for UseScaleFromDocument

Return type:

CADConvertOptions

Returns:

this object, for call chaining

SetZoomToExtents(value)

Sets the value for ZoomToExtents in the options object If enabled, the layout geometry is zoomed to the paper size, otherwise layout settings are applied. Enabled by default.

Parameters:

value: – the new value for ZoomToExtents

Return type:

CADConvertOptions

Returns:

this object, for call chaining

e_alphabetic_order = 1

Alphabetic sort order

e_alphanumeric_order = 2

Alphanumeric sort order (also called natural sort order)

e_default_order = 0

Default sort order. In this case there is no explicit sort performed, and pages are placed in the order they are encountered in the source document

property thisown

The membership flag

class apryse_sdk.CADModule

Bases: object

The class CADModule. static interface to PDFTron SDKs CAD functionality

static IsModuleAvailable()

Find out whether the CAD module is available (and licensed).

Return type:

boolean

Returns:

returns true if CAD operations can be performed.

property thisown

The membership flag

apryse_sdk.CADModule_IsModuleAvailable()

Find out whether the CAD module is available (and licensed).

Return type:

boolean

Returns:

returns true if CAD operations can be performed.

class apryse_sdk.Callback

Bases: object

SWIG director’s base class

Contains virtual functions which match the signature of the PDFNet function pointers. Each virtual function has a matching static function calling it. User extends this class in the target language and overrides the function of interest. The static function is assigned to the function pointer.

AnnotBitmapProc(operation_type, buffer, width, height, stride, page_num, annot_index, annot_key, x_in_page, y_in_page, x_offset, y_offset, remaining_tiles, sequence_number, x_page_size, y_page_size)

ConnectionErrorProc(message, error_code, switch_to_demo)

CreateTileProc(buffer, originX, originY, width, height, pagNum, cellNumber, finalRender, predictionRender, tilesRemaining, firstTile, canvasWidth, canvasHeight, cellSideLength, cellPerRow, cellPerCol, thumbnailId)

CurrentPageProc(current_page, num_pages)

CurrentZoomProc(curr_zoom_proc)

DeluxeCreateTileProc(buffer, width, height, stride, page_num, x_page_loc, y_page_loc, zoomed_page_width, zoomed_page_height, tile_id, x_in_page, y_in_page, canvas_id, remaining_tiles, tile_type, sequence_number)

ErrorReportProc(message)

FindTextHandler(success, selection)

JavaScriptEventProc(event_type, json)

PartDownloadedProc(dlType, doc, pageNum, objNum, message)

RemoveTileProc(canvasNumber, cellNumber, thumbnailId, sequenceNumber)

RenderBeginEventProc()

RenderFinishEventProc(cancelled)

RequestRenderInWorkerThread()

static StaticAnnotBitmapProc(me, operation_type, buffer, width, height, stride, page_num, annot_index, annot_key, x_in_page, y_in_page, x_offset, y_offset, remaining_tiles, sequence_number, x_page_size, y_page_size)

static StaticConnectionErrorProc(message, error_code, switch_to_demo, data)

static StaticCreateTileProc(customData, buffer, originX, originY, width, height, pageNum, cellNumber, finalRender, predictionRender, tilesRemaining, firstTile, canvasWidth, canvasHeight, cellSideLength, cellPerRow, cellPerCol, thumbnailId)

static StaticCurrentPageProc(current_page, num_pages, data)

static StaticCurrentZoomProc(curr_zoom_proc, data)

static StaticDeluxeCreateTileProc(me, buffer, width, height, stride, page_num, x_page_loc, y_page_loc, zoomed_page_width, zoomed_page_height, tile_id, x_in_page, y_in_page, canvas_id, remaining_tiles, tile_type, sequence_number)

static StaticErrorReportProc(message, data)

static StaticFindTextHandler(success, selection, custom_data)

static StaticJavaScriptEventProc(event_type, json, data)

static StaticPartDownloadedProc(dlType, doc, pageNum, objNum, message, customData)

static StaticRemoveTileProc(customData, canvasNumber, cellNumber, thumbnailId, sequenceNumber)

static StaticRenderBeginEventProc(data)

static StaticRenderFinishEventProc(data, cancelled)

static StaticRequestRenderInWorkerThread(custom_data)

static StaticThumbAsyncHandler(page_num, was_thumb_found, thumb_buf, thumb_width, thumb_height, custom_data)

ThumbAsyncHandler(page_num, was_thumb_found, thumb_buf, thumb_width, thumb_height)

property thisown

The membership flag

apryse_sdk.Callback_StaticAnnotBitmapProc(me, operation_type, buffer, width, height, stride, page_num, annot_index, annot_key, x_in_page, y_in_page, x_offset, y_offset, remaining_tiles, sequence_number, x_page_size, y_page_size)

apryse_sdk.Callback_StaticConnectionErrorProc(message, error_code, switch_to_demo, data)

apryse_sdk.Callback_StaticCreateTileProc(customData, buffer, originX, originY, width, height, pageNum, cellNumber, finalRender, predictionRender, tilesRemaining, firstTile, canvasWidth, canvasHeight, cellSideLength, cellPerRow, cellPerCol, thumbnailId)

apryse_sdk.Callback_StaticCurrentPageProc(current_page, num_pages, data)

apryse_sdk.Callback_StaticCurrentZoomProc(curr_zoom_proc, data)

apryse_sdk.Callback_StaticDeluxeCreateTileProc(me, buffer, width, height, stride, page_num, x_page_loc, y_page_loc, zoomed_page_width, zoomed_page_height, tile_id, x_in_page, y_in_page, canvas_id, remaining_tiles, tile_type, sequence_number)

apryse_sdk.Callback_StaticErrorReportProc(message, data)

apryse_sdk.Callback_StaticFindTextHandler(success, selection, custom_data)

apryse_sdk.Callback_StaticJavaScriptEventProc(event_type, json, data)

apryse_sdk.Callback_StaticPartDownloadedProc(dlType, doc, pageNum, objNum, message, customData)

apryse_sdk.Callback_StaticRemoveTileProc(customData, canvasNumber, cellNumber, thumbnailId, sequenceNumber)

apryse_sdk.Callback_StaticRenderBeginEventProc(data)

apryse_sdk.Callback_StaticRenderFinishEventProc(data, cancelled)

apryse_sdk.Callback_StaticRequestRenderInWorkerThread(custom_data)

apryse_sdk.Callback_StaticThumbAsyncHandler(page_num, was_thumb_found, thumb_buf, thumb_width, thumb_height, custom_data)

class apryse_sdk.Caret(args)

Bases: Markup

A Caret annotation (PDF 1.5) is a visual symbol that indicates the presence of text edits.

static Create(args)

Overload 1:

Creates a new Caret annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the Caret annotation is added.

• pos (Rect) – A rectangle specifying the Caret annotation’s bounds in default user space units.

Return type:

Caret

Returns:

A newly created blank Caret annotation.

Overload 2:

Creates a new Caret annotation, in the specified document, specifying a set of four numbers that shall describe the numerical differences between two rectangles: the Rect entry of the annotation and the actual boundaries of the underlying Caret.

Parameters:

• doc (SDFDoc) – A document to which the Caret annotation is added.

• pos (Rect) – A rectangle specifying the Caret annotation’s bounds in default user space units.

• padding (Rect) – A set of four numbers(represented as a Rect object)specifying the numerical differences between two rectangles: the Rect entry of the annotation and the actual boundaries of the underlying Caret.

Return type:

Caret

Returns:

A newly created Caret annotation with rectangle difference specified.

static CreateAnnot(args)

GetSymbol()

Returns the paragraph symbol associated with the caret.

Return type:

string

Returns:

The name of the symbol. This can be either “P” (Use a new paragraph symbol) or “None” (Don’t use any symbol). Default value: None.

SetSymbol(symbol)

Sets the caret symbol.

Parameters:

symbol (string) – The name of the symbol. This can be either “P” (Use a new paragraph symbol) or “None” (Don’t use any symbol). Default value: None.

property thisown

The membership flag

apryse_sdk.Caret_Create(args)

Overload 1:

Creates a new Caret annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the Caret annotation is added.

• pos (Rect) – A rectangle specifying the Caret annotation’s bounds in default user space units.

Return type:

Caret

Returns:

A newly created blank Caret annotation.

Overload 2:

Creates a new Caret annotation, in the specified document, specifying a set of four numbers that shall describe the numerical differences between two rectangles: the Rect entry of the annotation and the actual boundaries of the underlying Caret.

Parameters:

• doc (SDFDoc) – A document to which the Caret annotation is added.

• pos (Rect) – A rectangle specifying the Caret annotation’s bounds in default user space units.

• padding (Rect) – A set of four numbers(represented as a Rect object)specifying the numerical differences between two rectangles: the Rect entry of the annotation and the actual boundaries of the underlying Caret.

Return type:

Caret

Returns:

A newly created Caret annotation with rectangle difference specified.

apryse_sdk.Caret_CreateAnnot(args)

class apryse_sdk.CharIterator(args)

Bases: object

Supports a simple iteration over a generic collection.

Current()

Note: HasNext() must be true before calling Current()

Return type:

TRN_chardata

Returns:

the current element in the collection

Destroy()

Frees the native memory of the object.

HasNext()

Return type:

boolean

Returns:

true if the iterator can be successfully advanced to the next element; false if the iterator is no longer valid.

Next()

Note: HasNext() must be true before calling Next() Advances the iterator to the next element of the collection.

property mp_impl

property thisown

The membership flag

class apryse_sdk.CharRange

Bases: object

Represents a range of characters based on start index and length

property index

property length

property thisown

The membership flag

class apryse_sdk.CheckBoxWidget(args)

Bases: Widget

An object representing a check box used in a PDF Form.

static Create(args)

Overload 1:

Creates a new Check Box Widget annotation, in the specified document.

Parameters:

• doc (PDFDoc) – The document to which the annotation is to be added.

• pos (Rect) – A rectangle specifying the annotation’s bounds, specified in user space coordinates.

• field_name (string) – The name of the field for which to create a CheckBox widget.

Return type:

CheckBoxWidget

Returns:

A newly created blank Check Box Widget annotation.

Overload 2:

Creates a new Check Box Widget annotation, in the specified document.

Parameters:

• doc (PDFDoc) – The document to which the annotation is to be added.

• pos (Rect) – A rectangle specifying the annotation’s bounds, specified in user space coordinates.

• field (Field) – the field for which to create a CheckBox widget

Return type:

CheckBoxWidget

Returns:

A newly created blank Check Box Widget annotation.

IsChecked()

Returns whether the checkbox is checked.

Return type:

boolean

Returns:

A boolean value indicating whether the checkbox is checked.

SetChecked(checked)

Check or uncheck the Check Box Widget

Parameters:

value – If true, the annotation should be checked. Otherwise it should be unchecked.

property thisown

The membership flag

apryse_sdk.CheckBoxWidget_Create(args)

Overload 1:

Creates a new Check Box Widget annotation, in the specified document.

Parameters:

• doc (PDFDoc) – The document to which the annotation is to be added.

• pos (Rect) – A rectangle specifying the annotation’s bounds, specified in user space coordinates.

• field_name (string) – The name of the field for which to create a CheckBox widget.

Return type:

CheckBoxWidget

Returns:

A newly created blank Check Box Widget annotation.

Overload 2:

Creates a new Check Box Widget annotation, in the specified document.

Parameters:

• doc (PDFDoc) – The document to which the annotation is to be added.

• pos (Rect) – A rectangle specifying the annotation’s bounds, specified in user space coordinates.

• field (Field) – the field for which to create a CheckBox widget

Return type:

CheckBoxWidget

Returns:

A newly created blank Check Box Widget annotation.

class apryse_sdk.Circle(args)

Bases: Markup

A Circle annotation is a type of markup annotation that displays an ellipse on the page. When opened, it can display a pop-up window containing the text of the associated note. The ellipse may be inscribed and possibly padded within the annotation rectangle defined by the annotation dictionary’s Rect entry.

static Create(doc, pos)

Creates a new Circle annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds in default user space units.

Return type:

Circle

Returns:

A newly created blank Circle annotation.

static CreateAnnot(doc, pos)

property thisown

The membership flag

apryse_sdk.Circle_Create(doc, pos)

Creates a new Circle annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds in default user space units.

Return type:

Circle

Returns:

A newly created blank Circle annotation.

apryse_sdk.Circle_CreateAnnot(doc, pos)

class apryse_sdk.ClassMap(args)

Bases: object

GetSDFObj()

Returns the ClassMap dictionary.

Return type:

Obj

Returns:

the object to the underlying SDF/Cos object.

IsValid()

Return type:

boolean

Returns:

true if this is a valid (non-null) ClassMap, false otherwise. If the function returns false the underlying SDF/Cos object is null or is not valid and the ClassMap object should be treated as a null object.

property thisown

The membership flag

class apryse_sdk.ColorPt(args)

Bases: object

ColorPt is an array of colorants (or tint values) representing a color point in an associated color space.

Destroy()

Frees the native memory of the object.

Get(colorant_index)

The number of colorants depends on the associated color space. To find how many colorant are associated with a given color space use color_space.GetComponentNum().

For example, if you have a color point in the RGB color space you can extract its colorants as follows:

UInt8 rgb[3] = { UInt8(c.Get(0)255), UInt8(c.Get(1)255), UInt8(c.Get(2)255) };

Parameters:

colorant_index (int) – number representing the index of the color space to get the tint from

Return type:

double

Returns:

the tint value at a given colorant index.

Set(args)

Overload 1:

A utility method to set the first 4 tint values. For example, color.Set(red, green, blue) will initialize the ColorPt to given tint values.

Parameters:

• x (double) – initialized value of first color value (eg. red for rgb colorspace);

• y (double) – initialized value of second color value (eg. green for rgb colorspace);

• z (double) – initialized value of third color value (eg. blue for rgb colorspace);

• w (double) – initialized value of fourth color value (eg. when using CMYK);

Notes: color.Set(gray) is equivalent to Set(0, gray); All colorants should be in the range [0..1], so colors in the range [0..255] should be divided by 255.0 first.

Overload 2:

Sets a tint value at a given colorant index.

Parameters:

• colorant_index (int) – the color index. For example, for a color point associated with a Gray color space the only allowed value for index is 0. For a color point associated with a CMYK color space, the color_index can range from 0 (cyan) to 4 (black).

• colorant_value (double) – The new tint value.

For example, the following snippet will initialize the color point to [red, green, blue]:

color.SetColorantNum(3);
color.Set(0, red);
color.Set(1, green);
color.Set(2, blue);

The above code snippet is equivalent to the following line:

color.Set(red, green, blue)

Notes: If a color point has more than 4 colorants, SetColorantNum(num_colorants) must be called before getting or setting tint values. All colorants should be in the range [0..1], so colors in the range [0..255] should be divided by 255.0 first.

SetColorantNum(num)

If a color point has more than 4 colorants, SetColorantNum(num_colorants) must be called before getting or setting tint values. The number of colorants depends on the associated color space. To find how many colorant are associated with a given color space use color_space.GetComponentNum().

property m_c

property thisown

The membership flag

class apryse_sdk.ColorSpace(args)

Bases: object

This abstract class is used to serve as a color space tag to identify the specific color space of a Color object. It contains methods that transform colors in a specific color space to/from several color space such as DeviceRGB and DeviceCMYK.

For purposes of the methods in this class, colors are represented as arrays of color components represented as doubles in a normalized range defined by each ColorSpace. For many ColorSpaces (e.g. DeviceRGB), this range is 0.0 to 1.0. However, some ColorSpaces have components whose values have a different range. Methods are provided to inquire per component minimum and maximum normalized values.

Notes: Note that in Pattern color space (i.e. for ColorSpace::e_pattern) ‘color values’ are PDF::PatternColor objects instead of the numeric component values (i.e. ColorPt) used with other spaces.

Convert2CMYK(in_color)

A convenience function used to convert color points from the current color space to DeviceCMYK color space.

Parameters:

• in_color (ColorPt) – input color point in the current color space

• out_color – output color point in the DeviceCMYK color space

Notes: the number to input colorants must match the number of colorants expected by the current color space.

Convert2Gray(in_color)

A convenience function used to convert color points from the current color space to DeviceGray color space.

Parameters:

• in_color (ColorPt) – input color point in the current color space

• out_color – output color point in the DeviceGray color space

Notes: the number to input colorants must match the number of colorants expected by the current color space.

Convert2RGB(in_color)

A convenience function used to convert color points from the current color space to DeviceRGB color space.

Parameters:

• in_color (ColorPt) – input color point in the current color space

• out_color – output color point in the DeviceRGB color space

Notes: the number to input colorants must match the number of colorants expected by the current color space.

static CreateDeviceCMYK()

Create a new DeviceCMYK ColorSpace object

static CreateDeviceGray()

Create a new DeviceGray ColorSpace object

static CreateDeviceRGB()

Create a new DeviceRGB ColorSpace object

static CreateICC(args)

static CreatePattern()

Create a new Pattern ColorSpace object

Destroy()

Frees the native memory of the object.

GetAlternateColorSpace()

Return type:

ColorSpace

Returns:

the alternate color space if it is available or NULL otherwise. Color spaces that include alternate color space are e_separation, e_device_n, and e_icc.

GetBaseColor(color_idx)

Get the base color given a component value (index) in Indexed color space.

Parameters:

• color_idx (UChar) – color value represented in the index color space

• out_color – the color represented in the base (associated) color space

Notes: for color spaces other than Indexed this method throws an exception.

GetBaseColorSpace()

Return type:

ColorSpace

Returns:

the base color space if this is an e_indexed or e_pattern with associated base color space; NULL otherwise.

GetComponentNum()

Return type:

int

Returns:

The number of colorants (tint components) used to represent color point in this color space

GetHighVal()

Return type:

int

Returns:

the highest index for the color lookup table for Indexed color space. Since the color table is indexed from zero to highval, the actual number of entries is highval + 1. For color spaces other than indexed the method returns 0.

Notes: for color spaces other than Indexed this method throws an exception.

GetSDFObj()

Return type:

Obj

Returns:

the underlying SDF/Cos object

GetTintFunction()

Return type:

Function

Returns:

the function that transforms tint values into color component values in the alternate color space.

Notes: for color spaces other than Separation this method throws an exception.

GetType()

Return type:

int

Returns:

The type of this color space

InitColor(out_colorants)

Set color to the initial value used for this color space. The initial value depends on the color space (see 4.5.7 in PDF Ref. Manual).

Parameters:

out_colorants (ColorPt) – ColorPt object to initialize.

InitComponentRanges(out_decode_low, out_decode_range)

Initialize default ranges for each color component in the color space. For example, default ranges for DeviceRGB are [0 1 0 1 0 1] but for Lab the default values might be [0 100 -100 100 -100 100].

Parameters:

• out_decode_low (std::vector< double,std::allocator< double > >) – a vector of numbers representing the lower bound for each color component.

• out_decode_range (std::vector< double,std::allocator< double > >) – a vector of numbers representing the difference between high and low bound for each color component.

Notes: the size of resulting vectors will match the number of color components in this color space.

IsAll()

Return type:

boolean

Returns:

True if Separation color space contains the colorant All.

Notes: for color spaces other than Separation this method throws an exception.

IsNone()

Return type:

boolean

Returns:

True if Separation or DeviceN color space contains None colorants. For DeviceN the function returns true only if component colorant names are all None.

Notes: for color spaces other than Separation or DeviceN this method throws an exception.

e_cal_gray = 3

e_cal_rgb = 4

e_device_cmyk = 2

e_device_gray = 0

e_device_n = 10

e_device_rgb = 1

e_icc = 6

e_indexed = 7

e_lab = 5

e_null = 11

e_pattern = 8

e_separation = 9

property mp_cs

property thisown

The membership flag

apryse_sdk.ColorSpace_CreateDeviceCMYK()

Create a new DeviceCMYK ColorSpace object

apryse_sdk.ColorSpace_CreateDeviceGray()

Create a new DeviceGray ColorSpace object

apryse_sdk.ColorSpace_CreateDeviceRGB()

Create a new DeviceRGB ColorSpace object

apryse_sdk.ColorSpace_CreateICC(args)

apryse_sdk.ColorSpace_CreatePattern()

Create a new Pattern ColorSpace object

class apryse_sdk.ComboBoxWidget(args)

Bases: Widget

An object representing a combo box used in a PDF Form.

AddOption(value)

Adds an option to Combo Box widget.

Parameters:

value (string) – The option to add

AddOptions(opts)

Adds multiple options to Combo Box widget.

Parameters:

opts (std::vector< std::string,std::allocator< std::string > >) – The options to add

static Create(args)

Overload 1:

Creates a new Combo Box Widget annotation, in the specified document.

Parameters:

• doc (PDFDoc) – The document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds, specified in user space coordinates.

• field_name (string) – The name of the field for which to create a ComboBox widget

Return type:

ComboBoxWidget

Returns:

A newly created blank Combo Box Widget annotation.

Overload 2:

Creates a new Widget annotation, in the specified document.

Parameters:

• doc (PDFDoc) – The document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds, specified in user space coordinates.

• field (Field) – The field for which to create a Text widget

Return type:

ComboBoxWidget

Returns:

A newly created blank Widget annotation.

GetOptions()

Gets all options of the Combo Box widget.

Return type:

std::vector< std::string,std::allocator< std::string > >

Returns:

The options of the Combo Box widget

GetSelectedOption()

Retrieves the option selected in the ComboBox widget

Return type:

string

Returns:

The option selected in the ComboBox widget

RemoveOption(value)

Removes the option from Combo Box widget.

Parameters:

value (string) – The option to remove

ReplaceOptions(new_opts)

Replaces the current Combo Box widget options with a new set.

Parameters:

new_opts (std::vector< std::string,std::allocator< std::string > >) – The new set of options to use.

SetSelectedOption(value)

Selects the given option in the Combo Box widget

Parameters:

value (string) – The option to select

property thisown

The membership flag

apryse_sdk.ComboBoxWidget_Create(args)

Overload 1:

Creates a new Combo Box Widget annotation, in the specified document.

Parameters:

• doc (PDFDoc) – The document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds, specified in user space coordinates.

• field_name (string) – The name of the field for which to create a ComboBox widget

Return type:

ComboBoxWidget

Returns:

A newly created blank Combo Box Widget annotation.

Overload 2:

Creates a new Widget annotation, in the specified document.

Parameters:

• doc (PDFDoc) – The document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds, specified in user space coordinates.

• field (Field) – The field for which to create a Text widget

Return type:

ComboBoxWidget

Returns:

A newly created blank Widget annotation.

class apryse_sdk.Config(args)

Bases: object

The OCG::Config object represents an optional-content (OC) configuration structure (see section 4.10.3 in PDF Reference), used to persist a set of visibility states and other optional-content information in a PDF file A document has a default configuration, saved in the D entry in the ‘OCProperties’ dictionary (that can be obtained using pdfdoc.GetOCConfig()), and can have a list of other configurations, saved as an array in the ‘Configs’ entry in the OCProperties dictionary.

Configurations are typically used to initialize the OCG ON-OFF states for an optional-content context (OCG::Context). The OCG order in the configuration is the order in which the groups appear in the Layers panel of a PDF viewer. The configuration can also define a set of mutually exclusive OCGs, called a radio button group.

static Create(doc, default_config)

Creates a new optional-content configuration object in the document.

Parameters:

• doc (PDFDoc) – The document in which the new OCG::Config will be created.

• default_config (boolean) – If true, the configuration will be set as the default OCG configuration (i.e. listed as a D entry under ‘OCProperties’ dictionary).

Return type:

Config

Returns:

The newly created configuration object.

GetCreator()

Return type:

string

Returns:

the creator property of an optional-content configuration. The string is used to represent the name of the application or feature that created this configuration.

GetInitBaseState()

Return type:

string

Returns:

the base initialization state. This state is used to initialize the states

of all the OCGs in a document when this configuration is applied. The value of this entry must be one of the following names:

ON: The states of all groups are turned ON. OFF: The states of all groups are turned OFF. Unchanged: The states of all groups are left unchanged.

After base initialization, the contents of the ON and OFF arrays are processed, overriding

the state of the groups included in the arrays. Notes: If BaseState is present in the document’s default configuration dictionary, its value must be “ON”. ON.

GetInitOffStates()

Return type:

Obj

Returns:

the “OFF” initialization array from the configuration dictionary or NULL if the array is not present. The returned object is an array of optional content groups whose state should be set to OFF when this configuration is applied. Note: If the BaseState entry is OFF, this entry is redundant.

GetInitOnStates()

Return type:

Obj

Returns:

the “ON” initialization array from the configuration dictionary or NULL if the array is not present. The returned object is an array of optional content groups whose state should be set to ON when this configuration is applied. Note: If the BaseState entry is ON, this entry is redundant.

GetIntent()

Return type:

Obj

Returns:

OCG configuration intent. An intent is a name object (or an array of name objects) broadly describing the intended use, which can be either “View” or “Design”. A group’s content is considered to be optional (that is, the group’s state is considered in its visibility) if any intent in its list matches an intent of the context. The intent list of the context is usually set from the intent list of the document configuration. If the configuration has no Intent entry, the default value of “View” is used.

GetLockedOCGs()

Return type:

Obj

Returns:

the list of locked OCGs or NULL if there are no locked OCGs. The on/off state of a locked OCG cannot be toggled by the user through the user interface.

GetName()

Return type:

string

Returns:

the name of an optional-content configuration (suitable for presentation in a user interface).

GetOrder()

Return type:

Obj

Returns:

the Obj array that specifies the order of optional content (OC) groups in this configuration or NULL if the configuration does not contain any OCGs. The order of OCGs in the array is used to represent the order in which the group names are displayed in the Layers panel of a PDF viewer application. For more information, please refer to Section 4.10.3 in the PDF Reference.

GetSDFObj()

Return type:

Obj

Returns:

Pointer to the underlying SDF/Cos object.

IsValid()

Return type:

boolean

Returns:

true is this is a valid (non-null) configuration, false otherwise.

SetCreator(name)

Sets the creator property of an optional-content configuration. Stores the specified string as the Creator entry in the configuration’s SDF/Cos dictionary.

Parameters:

name (string) – The new creator string.

SetInitBaseState(args)

Sets the base initialization state. For more info, please see GetInitBaseState().

Parameters:

state (string) – new base state (“ON”, “OFF”, or “Unchanged”).

SetInitOffStates(off_array)

Sets the ‘OFF’ initialization array in the configuration dictionary.

Parameters:

off_array (Obj) – the initialization array to be used.

Notes: For more info, please see SetInitOffStates() and section 4.10.3 in PDF Reference.

SetInitOnStates(on_array)

Sets the ‘ON’ initialization array in the configuration dictionary.

Parameters:

on_array (Obj) – the initialization array to be used

Notes: For more info, please see SetInitOnStates() and section 4.10.3 in PDF Reference.

SetIntent(intent)

Sets the Intent entry in an optional-content configuration’s SDF/Cos dictionary. For more information, see GetIntent().

Parameters:

intent (Obj) – The new Intent entry value (a name object or an array of name objects).

SetLockedOCGs(locked_ocg_array)

Sets the array of locked OCGs. The on/off state of a locked OCG cannot be toggled by the user through the user interface.

Parameters:

locked_ocg_array (Obj) – An SDF/Cos array of OCG objects to be locked in this configuration, or an empty array if the configuration should not contain locked OCGs. The default is the empty array.

SetName(name)

Sets the name of an optional-content configuration (suitable for presentation in a user interface). The method stores the specified string as the Name entry in the configuration’s SDF/Cos dictionary.

Parameters:

name (string) – The new name string.

SetOrder(ocgs_array)

Sets the user interface display order of optional-content groups (OCGs) in this configuration. This is the order in which the group names are displayed in the Layers panel of a PDF viewer.

Parameters:

ocgs_array (Obj) – The SDF/Cos object containing the OCG order array. For more information, please refer to section 4.10.3 in the PDF Reference.

property mp_obj

property thisown

The membership flag

apryse_sdk.Config_Create(doc, default_config)

Creates a new optional-content configuration object in the document.

Parameters:

• doc (PDFDoc) – The document in which the new OCG::Config will be created.

• default_config (boolean) – If true, the configuration will be set as the default OCG configuration (i.e. listed as a D entry under ‘OCProperties’ dictionary).

Return type:

Config

Returns:

The newly created configuration object.

class apryse_sdk.ContentElement(args, kwargs)

Bases: object

Base class for all content elements in the document content tree. It contains methods to retrieve instances of derived classes via the AsDerivedClass() methods. The pattern is to retrieve a ElementRef<DerivedClass> object and then check if it is valid via the IsValid() method or casting to void. If it is valid, the actual derived instance can be accessed through the ElementRef<DerivedClass> object.

AsContentNode()

Retrieve the ElementRef<ContentNode> object for this content element which can be used to validate if this element is a content node and, if so, to retrieve an associated ContentNode object.

Return type:

Layout::ElementRef< Layout::ContentNode >

Returns:

The ElementRef<ContentNode> object

AsList()

Retrieve the ElementRef<List> object for this content element which can be used to validate if this element is a list and, if so, to retrieve an associated List object.

Return type:

Layout::ElementRef< Layout::List >

Returns:

The ElementRef<List> object

AsListItem()

Retrieve the ElementRef<List> object for this content element which can be used to validate if this element is a list item and, if so, to retrieve an associated ListItem object.

Return type:

Layout::ElementRef< Layout::ListItem >

Returns:

The ElementRef<ListItem> object

AsParagraph()

Retrieve the ElementRef<Paragraph> object for this content element. This can be used to check if this element is a paragraph and, if so, to access the associated Paragraph object.

Return type:

Layout::ElementRef< Layout::Paragraph >

Returns:

The ElementRef<Paragraph> object

AsTable()

Retrieve the ElementRef object for this content element. This can be used to check if this element is a table and, if so, to access the associated Table object.

Return type:

Layout::ElementRef< Layout::Table >

Returns:

The ElementRef object

AsTableCell()

Retrieve the ElementRef<TableCell> object for this content element. This can be used to check if this element is a table cell and, if so, to access the associated TableCell object.

Return type:

Layout::ElementRef< Layout::TableCell >

Returns:

The ElementRef<TableCell> object

AsTableRow()

Retrieve the ElementRef<TableRow> object for this content element. This can be used to check if this element is a table row and, if so, to access the associated TableRow object.

Return type:

Layout::ElementRef< Layout::TableRow >

Returns:

The ElementRef<TableRow> object

AsTextRun()

Retrieve the ElementRef<TextRun> object for this content element. This can be used to check if this element is a text run and, if so, to access the associated TextRun object.

Return type:

Layout::ElementRef< Layout::TextRun >

Returns:

The ElementRef<TextRun> object

Destroy()

GetTextStyledElement()

Retrieve the TextStyledElement object for manipulating the text style of this content element.

Return type:

TextStyledElement

Returns:

The TextStyledElement object

property m_impl

property thisown

The membership flag

class apryse_sdk.ContentItem(args)

Bases: object

Content items are graphical objects that exist in the document independently of the structure tree but are associated with structure elements.

Content items are leaf nodes of the structure tree.

GetContainingStm()

Return type:

Obj

Returns:

The stream object that contains the marked-content sequence. The function will return a non-NULL object only if the marked-content sequence resides in a content stream other than the content stream for the page (e.g. in a form XObject).

Notes: this method only applies to content items with type e_MCR.

GetMCID()

Return type:

int

Returns:

mcid (marked-content identifier).

Notes: this method only applies to content items with types e_MCR or e_MCID.

GetPage()

The page on which the marked content is drawn, whether directly as part of page content or indirectly by being in a Form XObject or annotation drawn on that page.

GetParent()

Find the parent structure element.

GetRefObj()

Return type:

Obj

Returns:

The referenced object.

Notes: this method only applies to content items with type e_OBJR.

GetSDFObj()

Return type:

Obj

Returns:

Pointer to the underlying SDF/Cos object.

GetStmOwner()

Return type:

Obj

Returns:

NULL or the PDF object owning the stream returned by GetContainingStm() (e.g. the annotation to which an appearance stream belongs).

Notes: this method only applies to content items with type e_MCR.

GetType()

Return type:

int

Returns:

the content item type.

e_MCID = 1

marked-content identifier.

e_MCR = 0

marked-content reference.

e_OBJR = 2

object reference dictionary.

e_Unknown = 3

unknown content type.

property mp_item

property thisown

The membership flag

class apryse_sdk.ContentNode(args, kwargs)

Bases: ContentElement

Base class for all elements in the document content tree that can contain other content elements.

Destroy()

GetContentNodeIterator()

Retrieve a ContentNodeIterator object from the content node

The ContentNodeIterator object can be used to traverse the children of the content node.

Return type:

ContentNodeIterator

Returns:

The ContentNodeIterator object

property thisown

The membership flag

class apryse_sdk.ContentNodeIterator(args)

Bases: object

Supports a simple iteration over a generic collection.

Current()

Note: HasNext() must be true before calling Current()

Return type:

ContentElement

Returns:

the current element in the collection

Destroy()

Frees the native memory of the object.

HasNext()

Return type:

boolean

Returns:

true if the iterator can be successfully advanced to the next element; false if the iterator is no longer valid.

Next()

Note: HasNext() must be true before calling Next() Advances the iterator to the next element of the collection.

property mp_impl

property thisown

The membership flag

class apryse_sdk.ContentReplacer

Bases: object

ContentReplacer is a utility class for replacing content (text and images) in existing PDF (template) documents.

Users can replace content in a PDF page using the following operations: - Replace an image that exists in a target rectangle with a replacement image. - Replace text that exists in a target rectangle with replacement text. - Replace all instances of a specially marked string with replacement string.

The following code replaces an image in a target region. This code also replaces the text “[NAME]” and “[JOB_TITLE]” with “John Smith” and “Software Developer” respectively. Notice the square braces (‘[’ and ‘]’) on the target strings in the original PDFDoc. These square braces are not included in the actual function calls below, as they’re implicitly added.

PDFDoc doc("../../TestFiles/BusinessCardTemplate.pdf");
doc.InitSecurityHandler();
ContentReplacer replacer;
Page page = doc.GetPage(1);
Image img = Image::Create(doc, "../../TestFiles/peppers.jpg");
replacer.AddImage(page.GetMediaBox(), img.GetSDFObj());
replacer.AddString("NAME", "John Smith");
replacer.AddString("JOB_TITLE", "Software Developer");
replacer.Process(page);

AddImage(target_region, replacement_image)

Replace the image that best fits into ‘target_region’ with ‘replacement_image’.

Parameters:

• target_region (Rect) –

  • The rectangle defining the area in which an image

  that best fits the rectangle will be replaced by ‘replacement_image’.

• replacement_image (Obj) –

  • The ‘SDF.Obj’ of a ‘PDF.Image’ object.

Notes: The best fit is the image that closest matches ‘target_region’. For example if there are two images on the page, one taking up all of the page, and the other smaller, and the smaller one has similar dimensions and position of ‘target_region’, then the smaller image would be replaced, not the larger. Furthermore, if ‘target_region’ encloses multiple images, then only the image with the largest area in ‘target_region’ will be replaced.

AddString(template_text, replacement_text)

Any text of the form “[template_text]” will be replaced by “replacement_text”.

Parameters:

• template_text (string) –

  • The text to remove.

• replacement_text (string) –

  • The new text that will appear in place of ‘template_text’.

Notes: Only text wrapped in ‘[’ and ‘]’ will be checked, and if it matches ‘template_text’, then ‘template_text’ and the surrounding square braces will be replaced by ‘replacement_text’. For example AddString(“TITLE”, “Doctor”) will replace any text consisting of “[TITLE]” with “Doctor”.

AddText(target_region, replacement_text)

All text inside ‘target_region’ will be deleted and replaced with ‘replacement_text’.

Parameters:

• target_region (Rect) –

  • The rectangle defining the area in which all text will

  be replaced by ‘replacement_text’.

• replacement_text (string) –

  • The new text that will replace the existing text

  in ‘target_region’.

Notes: The ‘replacement_text’ will be styled in the same font/color/style that is used by the original text. If there are multiple font styles, the most prevalent style will be used. Also, the ‘replacement_text’ will wrap within the ‘target_region’, but if it is too long, the overflow text will not be visible, and no surrounding content will be affected.

Destroy()

Frees the native memory of the object.

Process(page)

Apply the replacement instructions to the target page. Subsequent calls to ‘Process’ can be made on other pages, and it will apply the same rules.

Parameters:

page (Page) –

• The page to apply the content replacement instructions to.

SetMatchStrings(start_str, end_str)

Change the delimiters from ‘[’ and ‘]’ to arbitary strings.

Parameters:

• start_str (string) –

  • The starting delimiter string.

• end_str (string) –

  • The ending delimiter string.

Notes: While empty strings are allowed as delimiters, a warning is displayed. Otherwise there are no restrictions. For example, after SetMatchStrings(“<<”, “>>”), AddString(“TITLE”, “Doctor”) will replace any text consisting of “<<TITLE>>” with “Doctor”. Similarly, after SetMatchStrings(“Beginning…”, “…ending.”), AddString(“TITLE”, “Doctor”) will replace “Beginning…TITLE…ending.” with “Doctor”.

property mp_impl

property thisown

The membership flag

class apryse_sdk.Context(args)

Bases: object

The OCG::Context object represents an optional-content context in a document, within which document objects such as words or annotations are visible or hidden. The context keeps track of the ON-OFF states of all of the optional-content groups (OCGs) in a document. Content is or is not visible with respect to the OCG states stored in a specific context. Unlike other objects in OCG namespace, the OCG::Context does not correspond to any explicit PDF structure.

Each PDFView has a default context (PDF::GetOCGContext()) that it uses for on-screen drawing and that determines the default state for any drawing. The context has flags that control whether to draw content that is marked as optional, and whether to draw content that is not marked as optional.

When enumerating page content, OCG::Context can be passed as a parameter in ElementReader.Begin() method. When using PDFDraw, PDFRasterizer, or PDFView class to render PDF pages use PDFDraw::SetOCGContext() method to select an OC context.

There can be more than one Context object, representing different combinations of OCG states. You can change the states of OCGs within any context. You can build contexts with your own combination of OCG states, and issue drawing or enumeration commands using that context. For example, you can pass an optional-content context to ElementReader.Begin(). You can save the resulting state information as part of the configuration (e.g. using Config::SetInit methods), but the context itself has no corresponding PDF representation, and is not saved.

static CreateInternal(impl)

Destroy()

Frees the native memory of the object.

GetHandleInternal()

GetNonOCDrawing()

Return type:

boolean

Returns:

the non-OC status for this context. The flag indicates whether the content that is not marked as optional should be treated as visible. For more information, please see SetNonOCDrawing().

GetOCMode()

Return type:

int

Returns:

the drawing and enumeration type for this context. For more information, please see SetOCMode() and OCG::Context::OCDrawMode.

GetState(group)

Return type:

boolean

Returns:

the ON-OFF states (true or false) for the given optional-content group (OCG) in this OC context.

Parameters:

group (Group) – The optional-content group (OCG) that is queried.

IsValid()

Return type:

boolean

Returns:

true is this is a valid (non-null) context, false otherwise.

ResetStates(all_on)

Sets the sates of all OCGs in the context to ON or OFF.

Parameters:

all_on (boolean) – A flag used to specify whether the OCG states should be set to ON (if true), or OFF (if false).

SetNonOCDrawing(draw_non_OC)

Sets the non-OC status for this context. Content that is not marked as optional content is drawn (or element.IsOCVisible()) when ‘draw_non_OC’ is true, and not drawn/visible otherwise.

Parameters:

draw_non_OC (boolean) – A flag specifying whether the content that is not marked as optional should be treated as visible.

SetOCDrawMode(oc_draw_mode)

Sets the drawing and enumeration type for this context. This type, together with the visibility determined by the OCG and OCMD states, controls whether content that is marked as optional content is drawn or enumerated.

Parameters:

oc_draw_mode (int) – A flag specifying the visibility of optional content.

SetState(group, state)

Sets the ON-OFF states for the given optional-content group (OCG) in this context.

Parameters:

• group (Group) – The optional-content group (OCG) that is queried.

• state (boolean) – true for ‘ON’ and false for ‘OFF’.

e_AllOC = 1

Draw or enumerate all optional content, regardless of its visibility state. If the context’s ‘SetNonOCDrawing’ is enabled, all contents of document are shown.

e_NoOC = 2

Draw or enumerate no optional content, regardless of its visibility state. If the context’s ‘SetNonOCDrawing’ is not enabled, nothing is drawn, resulting in a blank page.

e_VisibleOC = 0

Draw or enumerate optional content that is visible, according to the current state of Optional Content Groups (OCGs) and Optional Content Membership Dictionaries (OCMDs). This is the default mode.

property mp_obj

property thisown

The membership flag

apryse_sdk.Context_CreateInternal(impl)

class apryse_sdk.ConversionMonitor(args)

Bases: object

Destroy()

Filter()

Next()

Progress()

Ready()

property m_owner

property mp_impl

property thisown

The membership flag

class apryse_sdk.ConversionOptions(args)

Bases: object

GetEnableExternalMediaDownloads()

Gets the value of EnableExternalMediaDownloads from the options object used to determine if downloading external resources is allowed during conversion.

Return type:

boolean

Returns:

a boolean value, the current value for EnableExternalMediaDownloads.

GetFileExtension()

Gets the value of FileExtension from the options object Override file extension used to determine conversion type.

Return type:

string

Returns:

a string, the current value for FileExtension.

GetInternalObj()

SetEnableExternalMediaDownloads(value)

Sets the value for EnableExternalMediaDownloads in the options object used to determine if downloading external resources is allowed during conversion.

Parameters:

value: – the new value for EnableExternalMediaDownloads.

Return type:

ConversionOptions

Returns:

this object, for call chaining.

SetFileExtension(value)

Sets the value for FileExtension in the options object Override file extension used to determine conversion type.

Parameters:

value: – the new value for FileExtension

Return type:

ConversionOptions

Returns:

this object, for call chaining

property thisown

The membership flag

class apryse_sdk.Convert(args, kwargs)

Bases: object

Converter is a utility class used to convert documents and files to PDF. Conversion of XPS, EMF and image files to PDF documents is performed internally. Other document formats are converted via native application and printing.

using namespace pdftron;
using namespace PDF;
PDFDoc pdfdoc;

Convert::FromXps(pdfdoc, input_path + "simple-xps.xps" );
Convert::FromEmf(pdfdoc, input_path + "simple-emf.emf" );
Convert::ToPdf(pdfdoc, input_path + test docx file.docx );

// Save the PDF document
UString outputFile = output_path + "ConverterTest.pdf";
pdfdoc.Save(outputFile, SDF::SDFDoc::e_remove_unused, NULL);

The PDFTron PDFNet printer needs to be installed to convert document formats. On Windows installation of printer drivers requires administrator UAC, manifests have been added to the Convert samples (C++, C# and Visual Basic).

To install the printer the process must be running as administrator. Execute:

Convert::Printer::Install();

Installation can take a few seconds, so it is recommended that you install the printer once as part of your deployment process. Duplicated installations will be quick since the presence of the printer is checked before installation is attempted. The printer is a virtual XPS printer supported on Vista and Windows 7, and on Windows XP with the XPS Essentials Pack.

There is no need to uninstall the printer after conversions, it can be left installed for later access. To uninstall the printer the process must be running as administrator. Execute:

Convert::Printer::Uninstall();

static CreateOfficeTemplate(args)

Overload 1:

Create a TemplateDocument object from an office file suitable for generating any number of PDFs from supplied template data.

Template filling will be performed entirely within PDFNet, and handles incoming files in .docx, .xlsx, .pptx, .doc, .ppt, and .xls format

This method does not perform any template filling and can be expected to return quickly. To do the actual work, use the returned TemplateDocument object

See also: TemplateDocument

Notes: Font requirements: on some systems you may need to specify extra font resources to aid in conversion. Please see http://www.pdftron.com/kb_fonts_and_builtin_office_conversion

Parameters:

• in_filename (string) – the path to the source document.

• options (ConversionOptions) – the office to pdf conversion options

Return type:

TemplateDocument

Returns:

A TemplateDocument object which encapsulates this particular office template.

See also: ConversionOptions

Overload 2:

Create a TemplateDocument object from an office file suitable for generating any number of PDFs from supplied template data.

Template filling will be performed entirely within PDFNet, and handles incoming files in .docx, .xlsx, .pptx, .doc, .ppt, and .xls format

This method does not perform any template filling and can be expected to return quickly. To do the actual work, use the returned TemplateDocument object

See also: TemplateDocument

Notes: Font requirements: on some systems you may need to specify extra font resources to aid in conversion. Please see http://www.pdftron.com/kb_fonts_and_builtin_office_conversion

Parameters:

• in_stream (Filter) – the source document data.

• options (ConversionOptions) – the office to pdf conversion options

Return type:

TemplateDocument

Returns:

A TemplateDocument object which encapsulates this particular office template.

See also: ConversionOptions

static CreateReflow(in_page, json_zones)

static FromCAD(in_pdfdoc, in_filename, opts=None)

Convert the specified CAD file to PDF and append converted pages to the specified PDF document. This conversion requires that the optional PDFTron CAD add-on module is available. See the CADConvertOptions class for the available options. See also: the ‘CADModule’ class

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to append to

• in_filename (string) – the path to the CAD document to convert

• opts (CADConvertOptions) – The options to use when converting.

static FromDICOM(in_pdfdoc, in_filename, opts=None)

Convert the specified AdvancedImaging file to PDF and append converted pages to the specified PDF document. This conversion requires that the optional PDFTron AdvancedImaging add-on module is available. See also: the ‘AdvancedImagingModule’ class

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to append to

• in_filename (string) – the path to the CAD document to convert

• opts (AdvancedImagingConvertOptions) – The options to use when converting.

static FromEmf(in_pdfdoc, in_filename)

Convert the specified EMF to PDF and append converted pages to to the specified PDF document. EMF will be fitted to the page.

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to append to

• in_filename (string) – the path to the EMF document to convert

Notes: This method is available only on Windows platforms.

static FromSVG(in_pdfdoc, in_filename, opts=None)

Convert the specified SVG file to PDF and append converted pages to the specified PDF document.

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to append to

• in_filename (string) – the path to the CAD document to convert

• opts (SVGConvertOptions) – The options to use when converting.

static FromText(args)

Convert the specified plain text file to PDF and append converted pages to the specified PDF document.

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to append to

• in_filename (string) – the path to the plain text document to convert

• in_options (Obj) – the conversion options. The available options are:

Option Name | Type | Note |

|-------------------------|———|---------------------------------------------------------| | BytesPerBite | Integer | In bytes. Use for streaming conversion only. | | FontFace | String | Set the font face used for the conversion. | | FontSize | Integer | Set the font size used for the conversion. | | LineHeightMultiplier | Double | Set the line height multiplier used for the conversion. | | MarginBottom | Double | In inches. Set the bottom margin of the page. | | MarginLeft | Double | In inches. Set the left margin of the page. | | MarginRight | Double | In inches. Set the right margin of the page. | | MarginTop | Double | In inches. Set the top margin of the page. | | PageHeight | Double | In inches. Set the page height. | | PageWidth | Double | In inches. Set the page width. | | UseSourceCodeFormatting | Boolean | Set whether to use mono font for the conversion. |

static FromTiff(in_pdfdoc, in_data)

Convert the specified TIFF filter to PDF and append converted pages to the specified PDF document.

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to append to

• in_data (Filter) – the source TIFF data.

static FromXps(args)

Overload 1:

Convert the specified XPS document to PDF and append converted pages to the specified PDF document.

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to append to

• in_filename (string) – the path to the XPS document to convert

Overload 2:

Convert the specified XPS document contained in memory to PDF and append converted pages to the specified PDF document.

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to append to

• buf (string) – the buffer containing the xps document

• buf_sz (int) – the size of the buffer

static OfficeToPDF(args)

Overload 1:

Convert the an office document (in .docx, .xlsx, pptx, or .doc format) to pdf and append to the specified PDF document. This conversion is performed entirely within PDFNet, and does not rely on Word interop or any other external functionality.

Notes: Font requirements: on some systems you may need to specify extra font resources to aid in conversion. Please see http://www.pdftron.com/kb_fonts_and_builtin_office_conversion

Parameters:

• in_pdfdoc (PDFDoc) – the conversion result will be appended to this pdf.

• in_filename (string) – the path to the source document.

• options (ConversionOptions) – the conversion options

Raises:

PDFNetException

See also: ConversionOptions

See also: StreamingPDFConversion() if you would like more control over the conversion process

Overload 2:

Convert the an office document (in .docx, .xlsx, pptx, or .doc format) to pdf and append to the specified PDF document. This conversion is performed entirely within PDFNet, and does not rely on Word interop or any other external functionality.

Notes: Font requirements: on some systems you may need to specify extra font resources to aid in conversion. Please see http://www.pdftron.com/kb_fonts_and_builtin_office_conversion

Parameters:

• in_pdfdoc (PDFDoc) – the conversion result will be appended to this pdf.

• in_stream (Filter) – the source document data.

• options (ConversionOptions) – the conversion options

Raises:

PDFNetException

See also: ConversionOptions

See also: StreamingPDFConversion() if you would like more control over the conversion process

static PageToHtml(page)

Convert a page to HTML and return a string of the html

Parameters:

page (Page) – the page to convert to HTML

Return type:

string

Returns:

a string containing the page’s html

static PageToHtmlZoned(page, json_zones)

static RequiresPrinter(in_filename)

Utility function to determine if ToPdf or ToXps will require the PDFNet printer to convert a specific external file to PDF.

Parameters:

in_filename (string) – the path to the document to be checked

Return type:

boolean

Returns:

true if ToPdf requires the printer to convert the file, false otherwise.

Notes: Current implementation looks only at the file extension not file contents. If the file extension is missing, false will be returned

static StreamingPDFConversion(args)

Overload 1:

Create a DocumentConversion object suitable for converting a file to pdf and appending to the specified PDF document. Handles incoming files in .docx, .xlsx, .pptx, .doc, .ppt, .xls, .png, .jpg, .bmp, .gif, .jp2, .tif, .txt, .xml and .md format This conversion will be performed entirely within PDFNet, and does not rely on any external functionality.

This method allows for more control over the conversion process than the single call ToPDF() interface. It does not perform any conversion logic immediately, and can be expected to return quickly. To perform the actual conversion, use the returned DocumentConversion object.

See also: DocumentConversion

Notes: Font requirements: on some systems you may need to specify extra font resources to aid in conversion. Please see http://www.pdftron.com/kb_fonts_and_builtin_office_conversion

Parameters:

• in_pdfdoc (PDFDoc) – the conversion result will be appended to this pdf.

• in_filename (string) – the path to the source document.

• options (ConversionOptions) – the conversion options

Return type:

DocumentConversion

Returns:

A DocumentConversion object which encapsulates this particular conversion.

See also: ConversionOptions

Overload 2:

Create a DocumentConversion object suitable for converting a file to pdf. Handles incoming files in .docx, .xlsx, .pptx, .doc, .ppt, .xls, .png, .jpg, .bmp, .gif, .jp2, .tif, .txt, .xml and .md format This conversion will be performed entirely within PDFNet, and does not rely on any external functionality.

This method allows for more control over the conversion process than the single call ToPDF() interface. It does not perform any conversion logic immediately, and can be expected to return quickly. To perform the actual conversion, use the returned DocumentConversion object.

See also: DocumentConversion

Notes: Font requirements: on some systems you may need to specify extra font resources to aid in conversion. Please see http://www.pdftron.com/kb_fonts_and_builtin_office_conversion

Parameters:

• in_filename (string) – the path to the source document.

• options (ConversionOptions) – the conversion options

Return type:

DocumentConversion

Returns:

A DocumentConversion object which encapsulates this particular conversion.

See also: ConversionOptions

Overload 3:

Create a DocumentConversion object suitable for converting an office document (in .docx, .xlsx, pptx, or .doc format) to pdf and appending to the specified PDF document. This conversion will be performed entirely within PDFNet, and does not rely on Word interop or any other external functionality.

This method does not perform any conversion logic and can be expected to return quickly. To do the actual conversion, use the returned DocumentConversion object.

See also: DocumentConversion

Notes: Font requirements: on some systems you may need to specify extra font resources to aid in conversion. Please see http://www.pdftron.com/kb_fonts_and_builtin_office_conversion

Parameters:

• in_pdfdoc (PDFDoc) – the conversion result will be appended to this pdf.

• in_stream (Filter) – the source document data.

• options (ConversionOptions) – the conversion options

Return type:

DocumentConversion

Returns:

A DocumentConversion object which encapsulates this particular conversion.

See also: ConversionOptions

Overload 4:

Create a DocumentConversion object suitable for converting an office document (in .docx, .xlsx, pptx, or .doc format) to pdf and appending to the specified PDF document. This conversion will be performed entirely within PDFNet, and does not rely on Word interop or any other external functionality.

This method does not perform any conversion logic and can be expected to return quickly. To do the actual conversion, use the returned DocumentConversion object.

See also: DocumentConversion

Notes: Font requirements: on some systems you may need to specify extra font resources to aid in conversion. Please see http://www.pdftron.com/kb_fonts_and_builtin_office_conversion

Parameters:

• in_stream (Filter) – the source document data.

• options (ConversionOptions) – the conversion options

Return type:

DocumentConversion

Returns:

A DocumentConversion object which encapsulates this particular conversion.

See also: ConversionOptions

static ToEmf(args)

Overload 1:

Convert the PDFDoc to EMF and save to the specified path

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to convert to EMF

• in_filename (string) – the path to the EMF files to create, one file per page

Notes: This method is available only on Windows platforms.

Overload 2:

Convert the Page to EMF and save to the specified path

Parameters:

• in_page (Page) – the Page to convert to EMF

• in_filename (string) – the path to the EMF file to create

Notes: This method is available only on Windows platforms.

static ToEpub(args)

Overload 1:

Convert a file to EPUB format and save to the specified path

Parameters:

• in_filename (string) – the file to convert to EPUB

• out_path (string) – the path to the EPUB file to create

• html_options (HTMLOutputOptions) – the conversion options

• epub_options (EPUBOutputOptions) – the conversion options

See also: HTMLOutputOptions

See also: EPUBOutputOptions

See also: ToPdf()

Notes: Requires the Convert::Printer class for all file formats that ToPdf also requires.

Overload 2:

Convert a file to EPUB format and save to the specified path

Parameters:

• in_filename (string) – the file to convert to EPUB

• out_path (string) – the path to the EPUB file to create

• html_options (HTMLOutputOptions) – the conversion options

See also: HTMLOutputOptions

See also: ToPdf()

Notes: Requires the Convert::Printer class for all file formats that ToPdf also requires.

Overload 3:

Convert a file to EPUB format and save to the specified path

Parameters:

• in_filename (string) – the file to convert to EPUB

• out_path (string) – the path to the EPUB file to create

See also: ToPdf()

Notes: Requires the Convert::Printer class for all file formats that ToPdf also requires.

Overload 4:

Convert the PDFDoc to EPUB format and save to the specified path

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to convert to EPUB

• out_path (string) – the path to the EPUB file to create

• html_options (HTMLOutputOptions) – the conversion options

• epub_options (EPUBOutputOptions) – the conversion options

See also: HTMLOutputOptions

See also: EPUBOutputOptions

See also: ToPdf()

Overload 5:

Convert the PDFDoc to EPUB format and save to the specified path

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to convert to EPUB

• out_path (string) – the path to the EPUB file to create

• html_options (HTMLOutputOptions) – the conversion options

See also: HTMLOutputOptions

See also: ToPdf()

Overload 6:

Convert the PDFDoc to EPUB format and save to the specified path

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to convert to EPUB

• out_path (string) – the path to the EPUB file to create

See also: ToPdf()

static ToExcel(args)

Overload 1:

Convert a PDF file to Excel and save the output to the specified path. This conversion requires that the optional PDFTron StructuredOutput add-on module is available.

Parameters:

• in_filename (string) – the file to convert to Excel

• out_path (string) – the path to where generated content will be stored

• options (ExcelOutputOptions) – the conversion options

See also: ExcelOutputOptions

See also: StructuredOutputModule

Overload 2:

Convert a PDF file to Excel and save the output to the specified path. This conversion requires that the optional PDFTron StructuredOutput add-on module is available.

Parameters:

• in_filename (string) – the file to convert to Excel

• out_path (string) – the path to where generated content will be stored

See also: StructuredOutputModule

Overload 3:

Convert PDF to Excel and save the output to the specified path. This conversion requires that the optional PDFTron StructuredOutput add-on module is available.

Parameters:

• in_pdfdoc (PDFDoc) – the PDF doc to convert to Excel

• out_path (string) – the path to where generated content will be stored

• options (ExcelOutputOptions) – the conversion options

See also: ExcelOutputOptions

See also: StructuredOutputModule

See also: ToPdf()

Overload 4:

Convert PDF to Excel and save the output to the specified path. This conversion requires that the optional PDFTron StructuredOutput add-on module is available.

Parameters:

• in_pdfdoc (PDFDoc) – the PDF doc to convert to Excel

• out_path (string) – the path to where generated content will be stored

See also: StructuredOutputModule

See also: ToPdf()

static ToHtml(args)

Overload 1:

Convert a file to HTML and save to the specified path. In e_reflow_paragraphs mode, this conversion requires that the optional PDFTron StructuredOutput add-on module is available.

Parameters:

• in_filename (string) – the file to convert to HTML

• out_path (string) – the path to where generated content will be stored

• options (HTMLOutputOptions) – the conversion options

See also: HTMLOutputOptions

See also: ToPdf()

See also: StructuredOutputModule

Notes: Requires the Convert::Printer class for all file formats that ToPdf also requires.

Overload 2:

Convert a file to HTML and save to the specified path

Parameters:

• in_filename (string) – the file to convert to HTML

• out_path (string) – the path to where generated content will be stored

See also: ToPdf()

Notes: Requires the Convert::Printer class for all file formats that ToPdf also requires.

Overload 3:

Convert the PDF to HTML and save to the specified path. In e_reflow_paragraphs mode, this conversion requires that the optional PDFTron StructuredOutput add-on module is available.

Parameters:

• in_pdfdoc (PDFDoc) – the PDF doc to convert to HTML

• out_path (string) – the path to where generated content will be stored

• options (HTMLOutputOptions) – the conversion options

See also: HTMLOutputOptions

See also: ToPdf()

See also: StructuredOutputModule

Overload 4:

Convert the PDF to HTML and save to the specified path

Parameters:

• in_pdfdoc (PDFDoc) – the PDF doc to convert to HTML

• out_path (string) – the path to where generated content will be stored

See also: ToPdf()

static ToPdf(in_pdfdoc, in_filename)

Convert the file or document to PDF and append to the specified PDF document

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to append the converted document to. The PDFDoc can then be converted to XPS, EMF or SVG using the other functions in this class.

• in_filename (string) – the path to the document to be converted to pdf

Notes: Internally formats include BMP, EMF, JPEG, PNG, TIF, XPS.

Formats that require external applications for conversion use the Convert::Printer class and the PDFNet printer to be installed. This is only supported on Windows platforms. Document formats in this category include RTF(MS Word or Wordpad), TXT (Notepad or Wordpad), DOC and DOCX (MS Word), PPT and PPTX (MS PowerPoint), XLS and XLSX (MS Excel), OpenOffice documents, HTML and MHT (Internet Explorer), PUB (MS Publisher), MSG (MS Outlook).

static ToPowerPoint(args)

Overload 1:

Convert a PDF file to PowerPoint and save the output to the specified path. This conversion requires that the optional PDFTron StructuredOutput add-on module is available.

Parameters:

• in_filename (string) – the file to convert to PowerPoint

• out_path (string) – the path to where generated content will be stored

• options (PowerPointOutputOptions) – the conversion options

See also: PowerPointOutputOptions

See also: StructuredOutputModule

Overload 2:

Convert a PDF file to PowerPoint and save the output to the specified path. This conversion requires that the optional PDFTron StructuredOutput add-on module is available.

Parameters:

• in_filename (string) – the file to convert to PowerPoint

• out_path (string) – the path to where generated content will be stored

See also: StructuredOutputModule

Overload 3:

Convert PDF to PowerPoint and save the output to the specified path. This conversion requires that the optional PDFTron StructuredOutput add-on module is available.

Parameters:

• in_pdfdoc (PDFDoc) – the PDF doc to convert to PowerPoint

• out_path (string) – the path to where generated content will be stored

• options (PowerPointOutputOptions) – the conversion options

See also: PowerPointOutputOptions

See also: StructuredOutputModule

See also: ToPdf()

Overload 4:

Convert PDF to PowerPoint and save the output to the specified path. This conversion requires that the optional PDFTron StructuredOutput add-on module is available.

Parameters:

• in_pdfdoc (PDFDoc) – the PDF doc to convert to PowerPoint

• out_path (string) – the path to where generated content will be stored

See also: StructuredOutputModule

See also: ToPdf()

static ToSvg(args)

Overload 1:

Convert the PDFDoc to SVG and save to the specified path

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to convert to SVG

• in_filename (string) – the path to the SVG files to create, one file per page

• in_options (SVGOutputOptions) – the conversion options

Overload 2:

Convert the PDFDoc to SVG and save to the specified path

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to convert to SVG

• in_filename (string) – the path to the SVG files to create, one file per page

Overload 3:

Convert the Page to SVG and save to the specified path

Parameters:

• in_page (Page) – the Page to convert to SVG

• in_filename (string) – the path to the SVG file to create

• in_options (SVGOutputOptions) – the conversion options

Overload 4:

Convert the Page to SVG and save to the specified path

Parameters:

• in_page (Page) – the Page to convert to SVG

• in_filename (string) – the path to the SVG file to create

static ToTiff(args)

Overload 1:

Convert a file to multipage TIFF and save to the specified path

Parameters:

• in_filename (string) – the file to convert to multipage TIFF

• out_path (string) – the path to the TIFF file to create

• options (TiffOutputOptions) – the conversion options

See also: TiffOutputOptions

Overload 2:

Convert a file to multipage TIFF and save to the specified path

Parameters:

• in_filename (string) – the file to convert to multipage TIFF

• out_path (string) – the path to the TIFF file to create

Overload 3:

Convert the PDF to multipage TIFF and save to the specified path

Parameters:

• in_pdfdoc (PDFDoc) – the PDF doc to convert to multipage TIFF

• out_path (string) – the path to the TIFF file to create

• options (TiffOutputOptions) – the conversion options

See also: TiffOutputOptions

Overload 4:

Convert the PDF to multipage TIFF and save to the specified path

Parameters:

• in_pdfdoc (PDFDoc) – the PDF doc to convert to multipage TIFF

• out_path (string) – the path to the TIFF file to create

Overload 5:

Convert a file to multipage TIFF and write to the provided filter

Parameters:

• in_filename (string) – the file to convert to multipage TIFF

• out_filter (Filter) – the output filter where the TIFF data will be written

• options (TiffOutputOptions) – the conversion options

See also: TiffOutputOptions

Overload 6:

Convert a file to multipage TIFF and write to the provided filter

Parameters:

• in_filename (string) – the file to convert to multipage TIFF

• out_filter (Filter) – the output filter where the TIFF data will be written

Overload 7:

Convert the PDF to multipage TIFF and write to the provided filter

Parameters:

• in_pdfdoc (PDFDoc) – the PDF doc to convert to multipage TIFF

• out_filter (Filter) – the output filter where the TIFF data will be written

• options (TiffOutputOptions) – the conversion options

See also: TiffOutputOptions

Overload 8:

Convert the PDF to multipage TIFF and write to the provided filter

Parameters:

• in_pdfdoc (PDFDoc) – the PDF doc to convert to multipage TIFF

• out_filter (Filter) – the output filter where the TIFF data will be written

static ToWord(args)

Overload 1:

Convert a PDF file to Word and save the output to the specified path. This conversion requires that the optional PDFTron StructuredOutput add-on module is available.

Parameters:

• in_filename (string) – the file to convert to Word

• out_path (string) – the path to where generated content will be stored

• options (WordOutputOptions) – the conversion options

See also: WordOutputOptions

See also: StructuredOutputModule

Overload 2:

Convert a PDF file to Word and save the output to the specified path. This conversion requires that the optional PDFTron StructuredOutput add-on module is available.

Parameters:

• in_filename (string) – the file to convert to Word

• out_path (string) – the path to where generated content will be stored

See also: StructuredOutputModule

Overload 3:

Convert PDF to Word and save the output to the specified path. This conversion requires that the optional PDFTron StructuredOutput add-on module is available.

Parameters:

• in_pdfdoc (PDFDoc) – the PDF doc to convert to Word

• out_path (string) – the path to where generated content will be stored

• options (WordOutputOptions) – the conversion options

See also: WordOutputOptions

See also: StructuredOutputModule

See also: ToPdf()

Overload 4:

Convert PDF to Word and save the output to the specified path. This conversion requires that the optional PDFTron StructuredOutput add-on module is available.

Parameters:

• in_pdfdoc (PDFDoc) – the PDF doc to convert to Word

• out_path (string) – the path to where generated content will be stored

See also: StructuredOutputModule

See also: ToPdf()

static ToXod(args)

Overload 1:

Convert the input file to XOD format and save to the specified path

Parameters:

• in_filename (string) – the file to convert to XOD

• out_filename (string) – the path to the XOD file to create

• options (XODOutputOptions) – the conversion options

See also: XODOutputOptions

See also: ToPdf()

Notes: Requires the Convert::Printer class for all file formats that ToPdf also requires.

Overload 2:

Convert the input file to XOD format and save to the specified path

Parameters:

• in_filename (string) – the file to convert to XOD

• out_filename (string) – the path to the XOD file to create

See also: ToPdf()

Notes: Requires the Convert::Printer class for all file formats that ToPdf also requires.

Overload 3:

Convert the input file to XOD format and save to the specified path

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to convert to XOD

• out_filename (string) – the path to the XOD file to create

• options (XODOutputOptions) – the conversion options

See also: XODOutputOptions

See also: ToPdf()

Overload 4:

Convert the input file to XOD format and save to the specified path

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to convert to XOD

• out_filename (string) – the path to the XOD file to create

See also: ToPdf()

Overload 5:

Generate a stream that incrementally converts the input file to XOD format.

Parameters:

• in_filename (string) – the file to convert to XOD

• options (XODOutputOptions) – the conversion options

Return type:

Filter

Returns:

A filter from which the file can be read incrementally.

See also: XODOutputOptions

See also: ToPdf()

Notes: Requires the Convert::Printer class for all file formats that ToPdf also requires.

Overload 6:

Generate a stream that incrementally converts the input file to XOD format.

Parameters:

in_filename (string) – the file to convert to XOD

Return type:

Filter

Returns:

A filter from which the file can be read incrementally.

See also: ToPdf()

Notes: Requires the Convert::Printer class for all file formats that ToPdf also requires.

Overload 7:

Generate a stream that incrementally converts the input file to XOD format.

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to convert to XOD

• options (XODOutputOptions) – the conversion options

Return type:

Filter

Returns:

A filter from which the file can be read incrementally.

See also: XODOutputOptions

See also: ToPdf()

Overload 8:

Generate a stream that incrementally converts the input file to XOD format.

Parameters:

in_pdfdoc (PDFDoc) – the PDFDoc to convert to XOD

Return type:

Filter

Returns:

A filter from which the file can be read incrementally.

See also: ToPdf()

static ToXodWithMonitor(args)

static ToXps(args)

Overload 1:

Convert the PDFDoc to XPS and save to the specified path

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to convert to XPS

• in_filename (string) – the path to the document to create

• options (XPSOutputOptions) – the conversion options

See also: XPSOutputOptions

Overload 2:

Convert the PDFDoc to XPS and save to the specified path

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to convert to XPS

• in_filename (string) – the path to the document to create

Overload 3:

Convert the input file to XPS format and save to the specified path

Parameters:

• in_inputFilename (string) – the file to convert to XPS

• in_outputFilename (string) – the path to the XPS file to create

• options (XPSOutputOptions) – the conversion options

See also: XPSOutputOptions

See also: ToPdf()

Notes: Requires the Convert::Printer class for all file formats that ToPdf also requires.

Overload 4:

Convert the input file to XPS format and save to the specified path

Parameters:

• in_inputFilename (string) – the file to convert to XPS

• in_outputFilename (string) – the path to the XPS file to create

See also: ToPdf()

Notes: Requires the Convert::Printer class for all file formats that ToPdf also requires.

static WordToPDF(args)

Overload 1:

Convert the a Word document (in .docx format) to pdf and append to the specified PDF document. This conversion is performed entirely within PDFNet, and does not rely on Word interop or any other external functionality.

Notes: Font requirements: on some systems you may need to specify extra font resources to aid in conversion. Please see http://www.pdftron.com/kb_fonts_and_builtin_office_conversion

Parameters:

• in_pdfdoc (PDFDoc) – the conversion result will be appended to this pdf.

• in_filename (string) – the path to the source document. The source must be in .docx format.

• options (WordToPDFOptions) – the conversion options

Raises:

PDFNetException

See also: WordToPDFOptions

See also: WordToPdfConversion() if you would like more control over the conversion process

Overload 2:

Convert the a Word document (in .docx format) to pdf and append to the specified PDF document. This conversion is performed entirely within PDFNet, and does not rely on Word interop or any other external functionality.

Notes: Font requirements: on some systems you may need to specify extra font resources to aid in conversion. Please see http://www.pdftron.com/kb_fonts_and_builtin_office_conversion

Parameters:

• in_pdfdoc (PDFDoc) – the conversion result will be appended to this pdf.

• in_stream (Filter) – the source document data. The source must be in .docx format.

• options (WordToPDFOptions) – the conversion options

Raises:

PDFNetException

See also: WordToPDFOptions

See also: WordToPdfConversion() if you would like more control over the conversion process

static WordToPDFConversion(args)

Overload 1:

Create a DocumentConversion object suitable for converting a Word document (in .docx format) to pdf and appending to the specified PDF document. This conversion will be performed entirely within PDFNet, and does not rely on Word interop or any other external functionality.

This method allows for more control over the conversion process than the single call WordToPDF() interface. This method does not perform any conversion logic and can be expected to return quickly. To do the actual conversion, use the returned DocumentConversion object.

See also: DocumentConversion

Notes: Font requirements: on some systems you may need to specify extra font resources to aid in conversion. Please see http://www.pdftron.com/kb_fonts_and_builtin_office_conversion

Parameters:

• in_pdfdoc (PDFDoc) – the conversion result will be appended to this pdf.

• in_filename (string) – the path to the source document. The source must be in .docx format.

• options (WordToPDFOptions) – the conversion options

Return type:

DocumentConversion

Returns:

A DocumentConversion object which encapsulates this particular conversion.

See also: WordToPDFOptions

Overload 2:

Create a DocumentConversion object suitable for converting a Word document (in .docx format) to pdf and appending to the specified PDF document. This conversion will be performed entirely within PDFNet, and does not rely on Word interop or any other external functionality.

This method allows for more control over the conversion process than the single call WordToPDF() interface. This method does not perform any conversion logic and can be expected to return quickly. To do the actual conversion, use the returned DocumentConversion object.

See also: DocumentConversion

Notes: Font requirements: on some systems you may need to specify extra font resources to aid in conversion. Please see http://www.pdftron.com/kb_fonts_and_builtin_office_conversion

Parameters:

• in_pdfdoc (PDFDoc) – the conversion result will be appended to this pdf.

• in_stream (Filter) – the source document data. The source must be in .docx format.

• options (WordToPDFOptions) – the conversion options

Return type:

DocumentConversion

Returns:

A DocumentConversion object which encapsulates this particular conversion.

See also: WordToPDFOptions

e_default = 2

Render text that are somewhat clipped or occluded.

e_fast = 2

Feature reduce PDF while trying to preserve some complex PDF features (such as vector figures, transparency, shadings, blend modes, Type3 fonts etc.) for pages that are already fast to render. This option can also result in smaller faster files compared to e_simple, but the pages may have more complex structure.

e_high_quality = 3

Preserve vector content where possible. In particular only feature reduce PDF files containing overprint or very complex vector content. Currently this option can only be used with XODOutputOptions.

e_keep_all = 4

Only render text that are completely occluded, or used as a clipping path.

e_keep_most = 3

Only render text that are seriously clipped or occluded.

e_off = 0

Disable flattening and convert all content as is.

e_simple = 1

Feature reduce PDF to a simple two layer representation consisting of a single background RGB image and a simple top text layer.

e_strict = 1

Render text that are marginally clipped or occluded.

e_very_strict = 0

Render (flatten) any text that is clipped or occluded.

property thisown

The membership flag

apryse_sdk.Convert_CreateOfficeTemplate(args)

Overload 1:

Create a TemplateDocument object from an office file suitable for generating any number of PDFs from supplied template data.

Template filling will be performed entirely within PDFNet, and handles incoming files in .docx, .xlsx, .pptx, .doc, .ppt, and .xls format

This method does not perform any template filling and can be expected to return quickly. To do the actual work, use the returned TemplateDocument object

See also: TemplateDocument

Notes: Font requirements: on some systems you may need to specify extra font resources to aid in conversion. Please see http://www.pdftron.com/kb_fonts_and_builtin_office_conversion

Parameters:

• in_filename (string) – the path to the source document.

• options (ConversionOptions) – the office to pdf conversion options

Return type:

TemplateDocument

Returns:

A TemplateDocument object which encapsulates this particular office template.

See also: ConversionOptions

Overload 2:

Create a TemplateDocument object from an office file suitable for generating any number of PDFs from supplied template data.

Template filling will be performed entirely within PDFNet, and handles incoming files in .docx, .xlsx, .pptx, .doc, .ppt, and .xls format

This method does not perform any template filling and can be expected to return quickly. To do the actual work, use the returned TemplateDocument object

See also: TemplateDocument

Notes: Font requirements: on some systems you may need to specify extra font resources to aid in conversion. Please see http://www.pdftron.com/kb_fonts_and_builtin_office_conversion

Parameters:

• in_stream (Filter) – the source document data.

• options (ConversionOptions) – the office to pdf conversion options

Return type:

TemplateDocument

Returns:

A TemplateDocument object which encapsulates this particular office template.

See also: ConversionOptions

apryse_sdk.Convert_CreateReflow(in_page, json_zones)

apryse_sdk.Convert_FromCAD(in_pdfdoc, in_filename, opts=None)

Convert the specified CAD file to PDF and append converted pages to the specified PDF document. This conversion requires that the optional PDFTron CAD add-on module is available. See the CADConvertOptions class for the available options. See also: the ‘CADModule’ class

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to append to

• in_filename (string) – the path to the CAD document to convert

• opts (CADConvertOptions) – The options to use when converting.

apryse_sdk.Convert_FromDICOM(in_pdfdoc, in_filename, opts=None)

Convert the specified AdvancedImaging file to PDF and append converted pages to the specified PDF document. This conversion requires that the optional PDFTron AdvancedImaging add-on module is available. See also: the ‘AdvancedImagingModule’ class

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to append to

• in_filename (string) – the path to the CAD document to convert

• opts (AdvancedImagingConvertOptions) – The options to use when converting.

apryse_sdk.Convert_FromEmf(in_pdfdoc, in_filename)

Convert the specified EMF to PDF and append converted pages to to the specified PDF document. EMF will be fitted to the page.

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to append to

• in_filename (string) – the path to the EMF document to convert

Notes: This method is available only on Windows platforms.

apryse_sdk.Convert_FromSVG(in_pdfdoc, in_filename, opts=None)

Convert the specified SVG file to PDF and append converted pages to the specified PDF document.

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to append to

• in_filename (string) – the path to the CAD document to convert

• opts (SVGConvertOptions) – The options to use when converting.

apryse_sdk.Convert_FromText(args)

Convert the specified plain text file to PDF and append converted pages to the specified PDF document.

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to append to

• in_filename (string) – the path to the plain text document to convert

• in_options (Obj) – the conversion options. The available options are:

Option Name | Type | Note |

|-------------------------|———|---------------------------------------------------------| | BytesPerBite | Integer | In bytes. Use for streaming conversion only. | | FontFace | String | Set the font face used for the conversion. | | FontSize | Integer | Set the font size used for the conversion. | | LineHeightMultiplier | Double | Set the line height multiplier used for the conversion. | | MarginBottom | Double | In inches. Set the bottom margin of the page. | | MarginLeft | Double | In inches. Set the left margin of the page. | | MarginRight | Double | In inches. Set the right margin of the page. | | MarginTop | Double | In inches. Set the top margin of the page. | | PageHeight | Double | In inches. Set the page height. | | PageWidth | Double | In inches. Set the page width. | | UseSourceCodeFormatting | Boolean | Set whether to use mono font for the conversion. |

apryse_sdk.Convert_FromTiff(in_pdfdoc, in_data)

Convert the specified TIFF filter to PDF and append converted pages to the specified PDF document.

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to append to

• in_data (Filter) – the source TIFF data.

apryse_sdk.Convert_FromXps(args)

Overload 1:

Convert the specified XPS document to PDF and append converted pages to the specified PDF document.

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to append to

• in_filename (string) – the path to the XPS document to convert

Overload 2:

Convert the specified XPS document contained in memory to PDF and append converted pages to the specified PDF document.

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to append to

• buf (string) – the buffer containing the xps document

• buf_sz (int) – the size of the buffer

apryse_sdk.Convert_OfficeToPDF(args)

Overload 1:

Convert the an office document (in .docx, .xlsx, pptx, or .doc format) to pdf and append to the specified PDF document. This conversion is performed entirely within PDFNet, and does not rely on Word interop or any other external functionality.

Notes: Font requirements: on some systems you may need to specify extra font resources to aid in conversion. Please see http://www.pdftron.com/kb_fonts_and_builtin_office_conversion

Parameters:

• in_pdfdoc (PDFDoc) – the conversion result will be appended to this pdf.

• in_filename (string) – the path to the source document.

• options (ConversionOptions) – the conversion options

Raises:

PDFNetException

See also: ConversionOptions

See also: StreamingPDFConversion() if you would like more control over the conversion process

Overload 2:

Convert the an office document (in .docx, .xlsx, pptx, or .doc format) to pdf and append to the specified PDF document. This conversion is performed entirely within PDFNet, and does not rely on Word interop or any other external functionality.

Notes: Font requirements: on some systems you may need to specify extra font resources to aid in conversion. Please see http://www.pdftron.com/kb_fonts_and_builtin_office_conversion

Parameters:

• in_pdfdoc (PDFDoc) – the conversion result will be appended to this pdf.

• in_stream (Filter) – the source document data.

• options (ConversionOptions) – the conversion options

Raises:

PDFNetException

See also: ConversionOptions

See also: StreamingPDFConversion() if you would like more control over the conversion process

apryse_sdk.Convert_PageToHtml(page)

Convert a page to HTML and return a string of the html

Parameters:

page (Page) – the page to convert to HTML

Return type:

string

Returns:

a string containing the page’s html

apryse_sdk.Convert_PageToHtmlZoned(page, json_zones)

apryse_sdk.Convert_RequiresPrinter(in_filename)

Utility function to determine if ToPdf or ToXps will require the PDFNet printer to convert a specific external file to PDF.

Parameters:

in_filename (string) – the path to the document to be checked

Return type:

boolean

Returns:

true if ToPdf requires the printer to convert the file, false otherwise.

Notes: Current implementation looks only at the file extension not file contents. If the file extension is missing, false will be returned

apryse_sdk.Convert_StreamingPDFConversion(args)

Overload 1:

Create a DocumentConversion object suitable for converting a file to pdf and appending to the specified PDF document. Handles incoming files in .docx, .xlsx, .pptx, .doc, .ppt, .xls, .png, .jpg, .bmp, .gif, .jp2, .tif, .txt, .xml and .md format This conversion will be performed entirely within PDFNet, and does not rely on any external functionality.

This method allows for more control over the conversion process than the single call ToPDF() interface. It does not perform any conversion logic immediately, and can be expected to return quickly. To perform the actual conversion, use the returned DocumentConversion object.

See also: DocumentConversion

Notes: Font requirements: on some systems you may need to specify extra font resources to aid in conversion. Please see http://www.pdftron.com/kb_fonts_and_builtin_office_conversion

Parameters:

• in_pdfdoc (PDFDoc) – the conversion result will be appended to this pdf.

• in_filename (string) – the path to the source document.

• options (ConversionOptions) – the conversion options

Return type:

DocumentConversion

Returns:

A DocumentConversion object which encapsulates this particular conversion.

See also: ConversionOptions

Overload 2:

Create a DocumentConversion object suitable for converting a file to pdf. Handles incoming files in .docx, .xlsx, .pptx, .doc, .ppt, .xls, .png, .jpg, .bmp, .gif, .jp2, .tif, .txt, .xml and .md format This conversion will be performed entirely within PDFNet, and does not rely on any external functionality.

This method allows for more control over the conversion process than the single call ToPDF() interface. It does not perform any conversion logic immediately, and can be expected to return quickly. To perform the actual conversion, use the returned DocumentConversion object.

See also: DocumentConversion

Notes: Font requirements: on some systems you may need to specify extra font resources to aid in conversion. Please see http://www.pdftron.com/kb_fonts_and_builtin_office_conversion

Parameters:

• in_filename (string) – the path to the source document.

• options (ConversionOptions) – the conversion options

Return type:

DocumentConversion

Returns:

A DocumentConversion object which encapsulates this particular conversion.

See also: ConversionOptions

Overload 3:

Create a DocumentConversion object suitable for converting an office document (in .docx, .xlsx, pptx, or .doc format) to pdf and appending to the specified PDF document. This conversion will be performed entirely within PDFNet, and does not rely on Word interop or any other external functionality.

This method does not perform any conversion logic and can be expected to return quickly. To do the actual conversion, use the returned DocumentConversion object.

See also: DocumentConversion

Notes: Font requirements: on some systems you may need to specify extra font resources to aid in conversion. Please see http://www.pdftron.com/kb_fonts_and_builtin_office_conversion

Parameters:

• in_pdfdoc (PDFDoc) – the conversion result will be appended to this pdf.

• in_stream (Filter) – the source document data.

• options (ConversionOptions) – the conversion options

Return type:

DocumentConversion

Returns:

A DocumentConversion object which encapsulates this particular conversion.

See also: ConversionOptions

Overload 4:

Create a DocumentConversion object suitable for converting an office document (in .docx, .xlsx, pptx, or .doc format) to pdf and appending to the specified PDF document. This conversion will be performed entirely within PDFNet, and does not rely on Word interop or any other external functionality.

This method does not perform any conversion logic and can be expected to return quickly. To do the actual conversion, use the returned DocumentConversion object.

See also: DocumentConversion

Notes: Font requirements: on some systems you may need to specify extra font resources to aid in conversion. Please see http://www.pdftron.com/kb_fonts_and_builtin_office_conversion

Parameters:

• in_stream (Filter) – the source document data.

• options (ConversionOptions) – the conversion options

Return type:

DocumentConversion

Returns:

A DocumentConversion object which encapsulates this particular conversion.

See also: ConversionOptions

apryse_sdk.Convert_ToEmf(args)

Overload 1:

Convert the PDFDoc to EMF and save to the specified path

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to convert to EMF

• in_filename (string) – the path to the EMF files to create, one file per page

Notes: This method is available only on Windows platforms.

Overload 2:

Convert the Page to EMF and save to the specified path

Parameters:

• in_page (Page) – the Page to convert to EMF

• in_filename (string) – the path to the EMF file to create

Notes: This method is available only on Windows platforms.

apryse_sdk.Convert_ToEpub(args)

Overload 1:

Convert a file to EPUB format and save to the specified path

Parameters:

• in_filename (string) – the file to convert to EPUB

• out_path (string) – the path to the EPUB file to create

• html_options (HTMLOutputOptions) – the conversion options

• epub_options (EPUBOutputOptions) – the conversion options

See also: HTMLOutputOptions

See also: EPUBOutputOptions

See also: ToPdf()

Notes: Requires the Convert::Printer class for all file formats that ToPdf also requires.

Overload 2:

Convert a file to EPUB format and save to the specified path

Parameters:

• in_filename (string) – the file to convert to EPUB

• out_path (string) – the path to the EPUB file to create

• html_options (HTMLOutputOptions) – the conversion options

See also: HTMLOutputOptions

See also: ToPdf()

Notes: Requires the Convert::Printer class for all file formats that ToPdf also requires.

Overload 3:

Convert a file to EPUB format and save to the specified path

Parameters:

• in_filename (string) – the file to convert to EPUB

• out_path (string) – the path to the EPUB file to create

See also: ToPdf()

Notes: Requires the Convert::Printer class for all file formats that ToPdf also requires.

Overload 4:

Convert the PDFDoc to EPUB format and save to the specified path

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to convert to EPUB

• out_path (string) – the path to the EPUB file to create

• html_options (HTMLOutputOptions) – the conversion options

• epub_options (EPUBOutputOptions) – the conversion options

See also: HTMLOutputOptions

See also: EPUBOutputOptions

See also: ToPdf()

Overload 5:

Convert the PDFDoc to EPUB format and save to the specified path

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to convert to EPUB

• out_path (string) – the path to the EPUB file to create

• html_options (HTMLOutputOptions) – the conversion options

See also: HTMLOutputOptions

See also: ToPdf()

Overload 6:

Convert the PDFDoc to EPUB format and save to the specified path

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to convert to EPUB

• out_path (string) – the path to the EPUB file to create

See also: ToPdf()

apryse_sdk.Convert_ToExcel(args)

Overload 1:

Convert a PDF file to Excel and save the output to the specified path. This conversion requires that the optional PDFTron StructuredOutput add-on module is available.

Parameters:

• in_filename (string) – the file to convert to Excel

• out_path (string) – the path to where generated content will be stored

• options (ExcelOutputOptions) – the conversion options

See also: ExcelOutputOptions

See also: StructuredOutputModule

Overload 2:

Convert a PDF file to Excel and save the output to the specified path. This conversion requires that the optional PDFTron StructuredOutput add-on module is available.

Parameters:

• in_filename (string) – the file to convert to Excel

• out_path (string) – the path to where generated content will be stored

See also: StructuredOutputModule

Overload 3:

Convert PDF to Excel and save the output to the specified path. This conversion requires that the optional PDFTron StructuredOutput add-on module is available.

Parameters:

• in_pdfdoc (PDFDoc) – the PDF doc to convert to Excel

• out_path (string) – the path to where generated content will be stored

• options (ExcelOutputOptions) – the conversion options

See also: ExcelOutputOptions

See also: StructuredOutputModule

See also: ToPdf()

Overload 4:

Convert PDF to Excel and save the output to the specified path. This conversion requires that the optional PDFTron StructuredOutput add-on module is available.

Parameters:

• in_pdfdoc (PDFDoc) – the PDF doc to convert to Excel

• out_path (string) – the path to where generated content will be stored

See also: StructuredOutputModule

See also: ToPdf()

apryse_sdk.Convert_ToHtml(args)

Overload 1:

Convert a file to HTML and save to the specified path. In e_reflow_paragraphs mode, this conversion requires that the optional PDFTron StructuredOutput add-on module is available.

Parameters:

• in_filename (string) – the file to convert to HTML

• out_path (string) – the path to where generated content will be stored

• options (HTMLOutputOptions) – the conversion options

See also: HTMLOutputOptions

See also: ToPdf()

See also: StructuredOutputModule

Notes: Requires the Convert::Printer class for all file formats that ToPdf also requires.

Overload 2:

Convert a file to HTML and save to the specified path

Parameters:

• in_filename (string) – the file to convert to HTML

• out_path (string) – the path to where generated content will be stored

See also: ToPdf()

Notes: Requires the Convert::Printer class for all file formats that ToPdf also requires.

Overload 3:

Convert the PDF to HTML and save to the specified path. In e_reflow_paragraphs mode, this conversion requires that the optional PDFTron StructuredOutput add-on module is available.

Parameters:

• in_pdfdoc (PDFDoc) – the PDF doc to convert to HTML

• out_path (string) – the path to where generated content will be stored

• options (HTMLOutputOptions) – the conversion options

See also: HTMLOutputOptions

See also: ToPdf()

See also: StructuredOutputModule

Overload 4:

Convert the PDF to HTML and save to the specified path

Parameters:

• in_pdfdoc (PDFDoc) – the PDF doc to convert to HTML

• out_path (string) – the path to where generated content will be stored

See also: ToPdf()

apryse_sdk.Convert_ToPdf(in_pdfdoc, in_filename)

Convert the file or document to PDF and append to the specified PDF document

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to append the converted document to. The PDFDoc can then be converted to XPS, EMF or SVG using the other functions in this class.

• in_filename (string) – the path to the document to be converted to pdf

Notes: Internally formats include BMP, EMF, JPEG, PNG, TIF, XPS.

Formats that require external applications for conversion use the Convert::Printer class and the PDFNet printer to be installed. This is only supported on Windows platforms. Document formats in this category include RTF(MS Word or Wordpad), TXT (Notepad or Wordpad), DOC and DOCX (MS Word), PPT and PPTX (MS PowerPoint), XLS and XLSX (MS Excel), OpenOffice documents, HTML and MHT (Internet Explorer), PUB (MS Publisher), MSG (MS Outlook).

apryse_sdk.Convert_ToPowerPoint(args)

Overload 1:

Convert a PDF file to PowerPoint and save the output to the specified path. This conversion requires that the optional PDFTron StructuredOutput add-on module is available.

Parameters:

• in_filename (string) – the file to convert to PowerPoint

• out_path (string) – the path to where generated content will be stored

• options (PowerPointOutputOptions) – the conversion options

See also: PowerPointOutputOptions

See also: StructuredOutputModule

Overload 2:

Convert a PDF file to PowerPoint and save the output to the specified path. This conversion requires that the optional PDFTron StructuredOutput add-on module is available.

Parameters:

• in_filename (string) – the file to convert to PowerPoint

• out_path (string) – the path to where generated content will be stored

See also: StructuredOutputModule

Overload 3:

Convert PDF to PowerPoint and save the output to the specified path. This conversion requires that the optional PDFTron StructuredOutput add-on module is available.

Parameters:

• in_pdfdoc (PDFDoc) – the PDF doc to convert to PowerPoint

• out_path (string) – the path to where generated content will be stored

• options (PowerPointOutputOptions) – the conversion options

See also: PowerPointOutputOptions

See also: StructuredOutputModule

See also: ToPdf()

Overload 4:

Convert PDF to PowerPoint and save the output to the specified path. This conversion requires that the optional PDFTron StructuredOutput add-on module is available.

Parameters:

• in_pdfdoc (PDFDoc) – the PDF doc to convert to PowerPoint

• out_path (string) – the path to where generated content will be stored

See also: StructuredOutputModule

See also: ToPdf()

apryse_sdk.Convert_ToSvg(args)

Overload 1:

Convert the PDFDoc to SVG and save to the specified path

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to convert to SVG

• in_filename (string) – the path to the SVG files to create, one file per page

• in_options (SVGOutputOptions) – the conversion options

Overload 2:

Convert the PDFDoc to SVG and save to the specified path

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to convert to SVG

• in_filename (string) – the path to the SVG files to create, one file per page

Overload 3:

Convert the Page to SVG and save to the specified path

Parameters:

• in_page (Page) – the Page to convert to SVG

• in_filename (string) – the path to the SVG file to create

• in_options (SVGOutputOptions) – the conversion options

Overload 4:

Convert the Page to SVG and save to the specified path

Parameters:

• in_page (Page) – the Page to convert to SVG

• in_filename (string) – the path to the SVG file to create

apryse_sdk.Convert_ToTiff(args)

Overload 1:

Convert a file to multipage TIFF and save to the specified path

Parameters:

• in_filename (string) – the file to convert to multipage TIFF

• out_path (string) – the path to the TIFF file to create

• options (TiffOutputOptions) – the conversion options

See also: TiffOutputOptions

Overload 2:

Convert a file to multipage TIFF and save to the specified path

Parameters:

• in_filename (string) – the file to convert to multipage TIFF

• out_path (string) – the path to the TIFF file to create

Overload 3:

Convert the PDF to multipage TIFF and save to the specified path

Parameters:

• in_pdfdoc (PDFDoc) – the PDF doc to convert to multipage TIFF

• out_path (string) – the path to the TIFF file to create

• options (TiffOutputOptions) – the conversion options

See also: TiffOutputOptions

Overload 4:

Convert the PDF to multipage TIFF and save to the specified path

Parameters:

• in_pdfdoc (PDFDoc) – the PDF doc to convert to multipage TIFF

• out_path (string) – the path to the TIFF file to create

Overload 5:

Convert a file to multipage TIFF and write to the provided filter

Parameters:

• in_filename (string) – the file to convert to multipage TIFF

• out_filter (Filter) – the output filter where the TIFF data will be written

• options (TiffOutputOptions) – the conversion options

See also: TiffOutputOptions

Overload 6:

Convert a file to multipage TIFF and write to the provided filter

Parameters:

• in_filename (string) – the file to convert to multipage TIFF

• out_filter (Filter) – the output filter where the TIFF data will be written

Overload 7:

Convert the PDF to multipage TIFF and write to the provided filter

Parameters:

• in_pdfdoc (PDFDoc) – the PDF doc to convert to multipage TIFF

• out_filter (Filter) – the output filter where the TIFF data will be written

• options (TiffOutputOptions) – the conversion options

See also: TiffOutputOptions

Overload 8:

Convert the PDF to multipage TIFF and write to the provided filter

Parameters:

• in_pdfdoc (PDFDoc) – the PDF doc to convert to multipage TIFF

• out_filter (Filter) – the output filter where the TIFF data will be written

apryse_sdk.Convert_ToWord(args)

Overload 1:

Convert a PDF file to Word and save the output to the specified path. This conversion requires that the optional PDFTron StructuredOutput add-on module is available.

Parameters:

• in_filename (string) – the file to convert to Word

• out_path (string) – the path to where generated content will be stored

• options (WordOutputOptions) – the conversion options

See also: WordOutputOptions

See also: StructuredOutputModule

Overload 2:

Convert a PDF file to Word and save the output to the specified path. This conversion requires that the optional PDFTron StructuredOutput add-on module is available.

Parameters:

• in_filename (string) – the file to convert to Word

• out_path (string) – the path to where generated content will be stored

See also: StructuredOutputModule

Overload 3:

Convert PDF to Word and save the output to the specified path. This conversion requires that the optional PDFTron StructuredOutput add-on module is available.

Parameters:

• in_pdfdoc (PDFDoc) – the PDF doc to convert to Word

• out_path (string) – the path to where generated content will be stored

• options (WordOutputOptions) – the conversion options

See also: WordOutputOptions

See also: StructuredOutputModule

See also: ToPdf()

Overload 4:

Convert PDF to Word and save the output to the specified path. This conversion requires that the optional PDFTron StructuredOutput add-on module is available.

Parameters:

• in_pdfdoc (PDFDoc) – the PDF doc to convert to Word

• out_path (string) – the path to where generated content will be stored

See also: StructuredOutputModule

See also: ToPdf()

apryse_sdk.Convert_ToXod(args)

Overload 1:

Convert the input file to XOD format and save to the specified path

Parameters:

• in_filename (string) – the file to convert to XOD

• out_filename (string) – the path to the XOD file to create

• options (XODOutputOptions) – the conversion options

See also: XODOutputOptions

See also: ToPdf()

Notes: Requires the Convert::Printer class for all file formats that ToPdf also requires.

Overload 2:

Convert the input file to XOD format and save to the specified path

Parameters:

• in_filename (string) – the file to convert to XOD

• out_filename (string) – the path to the XOD file to create

See also: ToPdf()

Notes: Requires the Convert::Printer class for all file formats that ToPdf also requires.

Overload 3:

Convert the input file to XOD format and save to the specified path

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to convert to XOD

• out_filename (string) – the path to the XOD file to create

• options (XODOutputOptions) – the conversion options

See also: XODOutputOptions

See also: ToPdf()

Overload 4:

Convert the input file to XOD format and save to the specified path

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to convert to XOD

• out_filename (string) – the path to the XOD file to create

See also: ToPdf()

Overload 5:

Generate a stream that incrementally converts the input file to XOD format.

Parameters:

• in_filename (string) – the file to convert to XOD

• options (XODOutputOptions) – the conversion options

Return type:

Filter

Returns:

A filter from which the file can be read incrementally.

See also: XODOutputOptions

See also: ToPdf()

Notes: Requires the Convert::Printer class for all file formats that ToPdf also requires.

Overload 6:

Generate a stream that incrementally converts the input file to XOD format.

Parameters:

in_filename (string) – the file to convert to XOD

Return type:

Filter

Returns:

A filter from which the file can be read incrementally.

See also: ToPdf()

Notes: Requires the Convert::Printer class for all file formats that ToPdf also requires.

Overload 7:

Generate a stream that incrementally converts the input file to XOD format.

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to convert to XOD

• options (XODOutputOptions) – the conversion options

Return type:

Filter

Returns:

A filter from which the file can be read incrementally.

See also: XODOutputOptions

See also: ToPdf()

Overload 8:

Generate a stream that incrementally converts the input file to XOD format.

Parameters:

in_pdfdoc (PDFDoc) – the PDFDoc to convert to XOD

Return type:

Filter

Returns:

A filter from which the file can be read incrementally.

See also: ToPdf()

apryse_sdk.Convert_ToXodWithMonitor(args)

apryse_sdk.Convert_ToXps(args)

Overload 1:

Convert the PDFDoc to XPS and save to the specified path

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to convert to XPS

• in_filename (string) – the path to the document to create

• options (XPSOutputOptions) – the conversion options

See also: XPSOutputOptions

Overload 2:

Convert the PDFDoc to XPS and save to the specified path

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to convert to XPS

• in_filename (string) – the path to the document to create

Overload 3:

Convert the input file to XPS format and save to the specified path

Parameters:

• in_inputFilename (string) – the file to convert to XPS

• in_outputFilename (string) – the path to the XPS file to create

• options (XPSOutputOptions) – the conversion options

See also: XPSOutputOptions

See also: ToPdf()

Notes: Requires the Convert::Printer class for all file formats that ToPdf also requires.

Overload 4:

Convert the input file to XPS format and save to the specified path

Parameters:

• in_inputFilename (string) – the file to convert to XPS

• in_outputFilename (string) – the path to the XPS file to create

See also: ToPdf()

Notes: Requires the Convert::Printer class for all file formats that ToPdf also requires.

apryse_sdk.Convert_WordToPDF(args)

Overload 1:

Convert the a Word document (in .docx format) to pdf and append to the specified PDF document. This conversion is performed entirely within PDFNet, and does not rely on Word interop or any other external functionality.

Notes: Font requirements: on some systems you may need to specify extra font resources to aid in conversion. Please see http://www.pdftron.com/kb_fonts_and_builtin_office_conversion

Parameters:

• in_pdfdoc (PDFDoc) – the conversion result will be appended to this pdf.

• in_filename (string) – the path to the source document. The source must be in .docx format.

• options (WordToPDFOptions) – the conversion options

Raises:

PDFNetException

See also: WordToPDFOptions

See also: WordToPdfConversion() if you would like more control over the conversion process

Overload 2:

Convert the a Word document (in .docx format) to pdf and append to the specified PDF document. This conversion is performed entirely within PDFNet, and does not rely on Word interop or any other external functionality.

Notes: Font requirements: on some systems you may need to specify extra font resources to aid in conversion. Please see http://www.pdftron.com/kb_fonts_and_builtin_office_conversion

Parameters:

• in_pdfdoc (PDFDoc) – the conversion result will be appended to this pdf.

• in_stream (Filter) – the source document data. The source must be in .docx format.

• options (WordToPDFOptions) – the conversion options

Raises:

PDFNetException

See also: WordToPDFOptions

See also: WordToPdfConversion() if you would like more control over the conversion process

apryse_sdk.Convert_WordToPDFConversion(args)

Overload 1:

Create a DocumentConversion object suitable for converting a Word document (in .docx format) to pdf and appending to the specified PDF document. This conversion will be performed entirely within PDFNet, and does not rely on Word interop or any other external functionality.

This method allows for more control over the conversion process than the single call WordToPDF() interface. This method does not perform any conversion logic and can be expected to return quickly. To do the actual conversion, use the returned DocumentConversion object.

See also: DocumentConversion

Notes: Font requirements: on some systems you may need to specify extra font resources to aid in conversion. Please see http://www.pdftron.com/kb_fonts_and_builtin_office_conversion

Parameters:

• in_pdfdoc (PDFDoc) – the conversion result will be appended to this pdf.

• in_filename (string) – the path to the source document. The source must be in .docx format.

• options (WordToPDFOptions) – the conversion options

Return type:

DocumentConversion

Returns:

A DocumentConversion object which encapsulates this particular conversion.

See also: WordToPDFOptions

Overload 2:

Create a DocumentConversion object suitable for converting a Word document (in .docx format) to pdf and appending to the specified PDF document. This conversion will be performed entirely within PDFNet, and does not rely on Word interop or any other external functionality.

This method allows for more control over the conversion process than the single call WordToPDF() interface. This method does not perform any conversion logic and can be expected to return quickly. To do the actual conversion, use the returned DocumentConversion object.

See also: DocumentConversion

Notes: Font requirements: on some systems you may need to specify extra font resources to aid in conversion. Please see http://www.pdftron.com/kb_fonts_and_builtin_office_conversion

Parameters:

• in_pdfdoc (PDFDoc) – the conversion result will be appended to this pdf.

• in_stream (Filter) – the source document data. The source must be in .docx format.

• options (WordToPDFOptions) – the conversion options

Return type:

DocumentConversion

Returns:

A DocumentConversion object which encapsulates this particular conversion.

See also: WordToPDFOptions

class apryse_sdk.DataExtractionModule

Bases: object

The class DataExtractionModule. static interface to Apryse SDKs data extraction functionality

static DetectAndAddFormFieldsToPDF(doc, options=None)

Perform automatic form field detection, then insert the fields into the PDF. Note: The FormKeyValue engine is experimental and subject to change.

Parameters:

• doc (PDFDoc) – – The PDF document where fields are detected from and inserted into.

• options (DataExtractionOptions) – – Data extraction options (optional).

static ExtractData(args)

Overload 1:

Perform data extraction on a PDF file using the specified engine and return the resulting JSON string. Note: The FormKeyValue engine is experimental and subject to change.

Parameters:

• input_pdf_file (string) – – The source document filename.

• engine (int) – – The extraction engine.

• options (DataExtractionOptions) – – Data extraction options (optional).

Return type:

string

Returns:

JSON string representing the extracted results.

Overload 2:

Perform data extraction on a PDF file using the specified engine. Note: The FormKeyValue engine is experimental and subject to change.

Parameters:

• input_pdf_file (string) – – The source document filename.

• output_json_file (string) – – The resulting JSON filename.

• engine (int) – – The extraction engine.

• options (DataExtractionOptions) – – Data extraction options (optional).

Overload 3:

Perform data extraction on a PDF file using the specified engine. Note: The FormKeyValue engine is experimental and subject to change.

Parameters:

• input_pdf_file (string) – – The source document filename.

• output_json_file (string) – – The resulting JSON filename.

• engine (int) – – The extraction engine.

• options – – Data extraction options (optional).

static ExtractToXLSX(args)

Overload 1:

Perform data extraction on a PDF in XLSX output format.

Parameters:

• input_pdf_file (string) – – The source document filename.

• output_xlsx_file (string) – – The resulting XLSX filename.

• options (DataExtractionOptions) – – Data extraction options (optional).

Overload 2:

Perform data extraction on a PDF in XLSX output format.

Parameters:

• input_pdf_file (string) – – The source document filename.

• output_xlsx_stream (Filter) – – The resulting XLSX filter.

• options (DataExtractionOptions) – – Data extraction options (optional).

Overload 3:

Perform data extraction on a PDF in XLSX output format.

Parameters:

• input_pdf_file (string) – – The source document filename.

• output_xlsx_stream (Filter) – – The resulting XLSX filter.

• options – – Data extraction options (optional).

static IsModuleAvailable(engine)

Find out whether the specified data extraction module is available (and licensed).

Parameters:

engine (int) – – The extraction engine.

Return type:

boolean

Returns:

returns true if data extraction operations can be performed.

e_DocStructure = 2

Document structure engine. This engine discovers the full logical structure, including headers, footers, paragraphs, list items, table columns, cells, borders, images and graphics.

e_Form = 1

Form field extraction engine. This engine uses artificial intelligence and computer vision to detect form fields in documents that do not have any interactive field annotations embedded.

e_FormKeyValue = 3

This engine is experimental and subject to change.

Type:

Form field with key value extraction engine. This engine uses artificial intelligence and computer vision to detect form fields, including field name and values, in documents that do not have any interactive field annotations embedded. Note

e_Tabular = 0

Tabular Data engine. This engine identifies column and row structure and analyzes numeric columns. It is especially suited to documents that are table-based such as spreadsheets.

property thisown

The membership flag

apryse_sdk.DataExtractionModule_DetectAndAddFormFieldsToPDF(doc, options=None)

Perform automatic form field detection, then insert the fields into the PDF. Note: The FormKeyValue engine is experimental and subject to change.

Parameters:

• doc (PDFDoc) – – The PDF document where fields are detected from and inserted into.

• options (DataExtractionOptions) – – Data extraction options (optional).

apryse_sdk.DataExtractionModule_ExtractData(args)

Overload 1:

Perform data extraction on a PDF file using the specified engine and return the resulting JSON string. Note: The FormKeyValue engine is experimental and subject to change.

Parameters:

• input_pdf_file (string) – – The source document filename.

• engine (int) – – The extraction engine.

• options (DataExtractionOptions) – – Data extraction options (optional).

Return type:

string

Returns:

JSON string representing the extracted results.

Overload 2:

Perform data extraction on a PDF file using the specified engine. Note: The FormKeyValue engine is experimental and subject to change.

Parameters:

• input_pdf_file (string) – – The source document filename.

• output_json_file (string) – – The resulting JSON filename.

• engine (int) – – The extraction engine.

• options (DataExtractionOptions) – – Data extraction options (optional).

Overload 3:

Perform data extraction on a PDF file using the specified engine. Note: The FormKeyValue engine is experimental and subject to change.

Parameters:

• input_pdf_file (string) – – The source document filename.

• output_json_file (string) – – The resulting JSON filename.

• engine (int) – – The extraction engine.

• options – – Data extraction options (optional).

apryse_sdk.DataExtractionModule_ExtractToXLSX(args)

Overload 1:

Perform data extraction on a PDF in XLSX output format.

Parameters:

• input_pdf_file (string) – – The source document filename.

• output_xlsx_file (string) – – The resulting XLSX filename.

• options (DataExtractionOptions) – – Data extraction options (optional).

Overload 2:

Perform data extraction on a PDF in XLSX output format.

Parameters:

• input_pdf_file (string) – – The source document filename.

• output_xlsx_stream (Filter) – – The resulting XLSX filter.

• options (DataExtractionOptions) – – Data extraction options (optional).

Overload 3:

Perform data extraction on a PDF in XLSX output format.

Parameters:

• input_pdf_file (string) – – The source document filename.

• output_xlsx_stream (Filter) – – The resulting XLSX filter.

• options – – Data extraction options (optional).

apryse_sdk.DataExtractionModule_IsModuleAvailable(engine)

Find out whether the specified data extraction module is available (and licensed).

Parameters:

engine (int) – – The extraction engine.

Return type:

boolean

Returns:

returns true if data extraction operations can be performed.

class apryse_sdk.DataExtractionOptions

Bases: object

GetDeepLearningAssist()

Gets the value DeepLearningAssist from the options object Specifies if Deep Learning is used with table recognition in the DocStructure engine. The default is false. When true, table recognition accuracy improves at the cost of increased processing time. This only affects the DocStructure engine.

Return type:

boolean

Returns:

a bool, the current value for DeepLearningAssist.

GetFormExtractionEngine()

Gets the value FormExtractionEngine from the options object Specifies the form extraction engine used in DetectAndAddFormFieldsToPDF, either ‘Form’ or ‘FormKeyValue’. The default is ‘Form’. Note: The ‘FormKeyValue’ engine is experimental and subject to change.

Return type:

string

Returns:

a string, the current value for FormExtractionEngine.

GetLanguage()

Gets the value Language from the options object Specifies the OCR language(s). Use 3-letter ISO 639-2 language codes, separated by spaces. Example: “eng deu spa fra”. The default is English.

Return type:

string

Returns:

a string, the current value for Language.

GetOverlappingFormFieldBehavior()

Gets the value OverlappingFormFieldBehavior from the options object When a detected form field overlaps with an existing one, keep either the old field (value ‘KeepOld’), or the new one (value ‘KeepNew’, default).

Return type:

string

Returns:

a string, the current value for OverlappingFormFieldBehavior.

GetPDFPassword()

Gets the value PDFPassword from the options object Specifies the password if the PDF requires one. The default is no password.

Return type:

string

Returns:

a string, the current value for PDFPassword.

GetPages()

Gets the value Pages from the options object Specifies a range of pages to be converted, such as “1-5”. By default all pages are converted. The first page has the page number of 1.

Return type:

string

Returns:

a string, the current value for Pages.

SetDeepLearningAssist(value)

Sets the value for DeepLearningAssist in the options object Specifies if Deep Learning is used with table recognition in the DocStructure engine. The default is false. When true, table recognition accuracy improves at the cost of increased processing time. This only affects the DocStructure engine.

Parameters:

value: – the new value for DeepLearningAssist

Return type:

DataExtractionOptions

Returns:

this object, for call chaining

SetFormExtractionEngine(value)

Sets the value for FormExtractionEngine in the options object Specifies the form extraction engine used in DetectAndAddFormFieldsToPDF, either ‘Form’ or ‘FormKeyValue’. The default is ‘Form’. Note: The ‘FormKeyValue’ engine is experimental and subject to change.

Parameters:

value: – the new value for FormExtractionEngine

Return type:

DataExtractionOptions

Returns:

this object, for call chaining

SetLanguage(value)

Sets the value for Language in the options object Specifies the OCR language(s). Use 3-letter ISO 639-2 language codes, separated by spaces. Example: “eng deu spa fra”. The default is English.

Parameters:

value: – the new value for Language

Return type:

DataExtractionOptions

Returns:

this object, for call chaining

SetOverlappingFormFieldBehavior(value)

Sets the value for OverlappingFormFieldBehavior in the options object When a detected form field overlaps with an existing one, keep either the old field (value ‘KeepOld’), or the new one (value ‘KeepNew’, default).

Parameters:

value: – the new value for OverlappingFormFieldBehavior

Return type:

DataExtractionOptions

Returns:

this object, for call chaining

SetPDFPassword(value)

Sets the value for PDFPassword in the options object Specifies the password if the PDF requires one. The default is no password.

Parameters:

value: – the new value for PDFPassword

Return type:

DataExtractionOptions

Returns:

this object, for call chaining

SetPages(value)

Sets the value for Pages in the options object Specifies a range of pages to be converted, such as “1-5”. By default all pages are converted. The first page has the page number of 1.

Parameters:

value: – the new value for Pages

Return type:

DataExtractionOptions

Returns:

this object, for call chaining

property thisown

The membership flag

class apryse_sdk.Date(args)

Bases: TRN_date

The Date class is a utility class used to simplify work with PDF date objects.

PDF defines a standard date format, which closely follows international standard ASN.1 (Abstract Syntax Notation One), A date is a string of the form (D:YYYYMMDDHHmmSSOHH’mm’); See PDF Reference Manual for details.

Date can be associated with a SDF/Cos date string using Date(Obj)ructor or later using Date::Attach(Obj) or Date::Update(Obj) methods.

Date keeps a local date/time cache so it is necessary to call Date::Update() method if the changes to the Date should be saved in the attached Cos/SDF string.

Attach(d)

Attach the Cos/SDF object to the Date.

Parameters:

d (Obj) –

• underlying Cos/SDF object. Must be an SDF::Str containing

a PDF date object.

GetDay()

GetHour()

GetMinute()

GetMonth()

GetSecond()

GetUT()

GetUTHour()

GetUTMin()

GetYear()

Return type:

int

Returns:

The year.

IsValid()

Indicates whether the Date is valid (non-null).

Return type:

boolean

Returns:

True if this is a valid (non-null) Date; otherwise false.

Notes: If this method returns false the underlying SDF/Cos object is null and the Date object should be treated as null as well.

SetCurrentTime()

Sets the date object to the current date and time. The method also updates associated SDF object.

SetUT(ut)

Set the relationship of local time to Universal Time(UT), denoted by one of the characters +, -, or Z

Parameters:

ut (char) – the relationship of local time to Universal Time(UT),

SetUTHour(ut_hour)

Set the absolute value of the offset from UT in hours(00-23)

Parameters:

ut_hour (Int8) – the absolute value of the offset from UT in hours(00-23)

SetUTMinutes(ut_minutes)

Set the absolute value of the offset from UT in minutes(00-59)

Parameters:

ut_minutes (Int8) – the absolute value of the offset from UT in minutes(00-59)

Update(d=0)

Saves changes made to the Date object in the attached (or specified) SDF/Cos string.

Parameters:

d (Obj) –

• an optional parameter indicating a SDF string that should be

updated and attached to this Date. If parameter d is NULL or is omitted, update is performed on previously attached Cos/SDF date.

Return type:

boolean

Returns:

true if the attached Cos/SDF string was successfully updated, false otherwise.

property thisown

The membership flag

class apryse_sdk.Destination(args)

Bases: object

A destination defines a particular view of a document, consisting of the following:

• The page of the document to be displayed

• The location of the document window on that page

• The magnification (zoom) factor to use when displaying the page

Destinations may be associated with Bookmarks, Annotations, and Remote Go-To Actions.

Destination is a utility class used to simplify work with PDF Destinations; Please refer to section 8.2.1 ‘Destinations’ in PDF Reference Manual for details.

static CreateFit(page)

Create a new ‘Fit’ Destination.

The new Destination displays the page designated by ‘page’, with its contents magnified just enough to fit the entire page within the window both horizontally and vertically. If the required horizontal and vertical magnification factors are different, use the smaller of the two, centering the page within the window in the other dimension.

Parameters:

page (Page) – Page object to display

static CreateFitB(page)

Create a new ‘FitB’ Destination.

The new Destination displays the page designated by ‘page’, with its contents magnified just enough to fit its bounding box entirely within the window both horizontally and vertically. If the required horizontal and vertical magnification factors are different, use the smaller of the two, centering the bounding box within the window in the other dimension.

Parameters:

page (Page) – Page object to display

static CreateFitBH(page, top)

Create a new ‘FitBH’ Destination.

The new Destination displays the page designated by ‘page’, with the vertical coordinate ‘top’ positioned at the top edge of the window and the contents of the page magnified just enough to fit the entire width of its bounding box within the window.

Parameters:

• page (Page) – Page object to display

• top (double) – vertical coordinate of the top edge of the window

static CreateFitBV(page, left)

Create a new ‘FitBV’ Destination.

The new Destination displays Display the page designated by ‘page’, with the horizontal coordinate ‘left’ positioned at the left edge of the window and the contents of the page magnified just enough to fit the entire height of its bounding box within the window.

Parameters:

• page (Page) – Page object to display

• left (double) – horizontal coordinate of the left edge of the window

static CreateFitH(page, top)

Create a new ‘FitH’ Destination.

The new Destination displays the page designated by ‘page’, with the vertical coordinate ‘top’ positioned at the top edge of the window and the contents of the page magnified just enough to fit the entire width of the page within the window.

Parameters:

• page (Page) – Page object to display

• top (double) – vertical coordinate of the top edge of the window

static CreateFitR(page, left, bottom, right, top)

Create a new ‘FitR’ Destination.

The new Destination displays the page designated by ‘page’, with its contents magnified just enough to fit the rectangle specified by the coordinates ‘left’, ‘bottom’, ‘right’, and ‘top’ entirely within the window both horizontally and vertically. If the required horizontal and vertical magnification factors are different, use the smaller of the two, centering the rectangle within the window in the other dimension.

Parameters:

• page (Page) – Page object to display

• left (double) – horizontal coordinate of the left edge of the window

• bottom (double) – vertical coordinate of the bottom edge of the window

• right (double) – horizontal coordinate of the right edge of the window

• top (double) – vertical coordinate of the top edge of the window

static CreateFitV(page, left)

Create a new ‘FitV’ Destination.

The new Destination displays the page designated by ‘page’, with the horizontal coordinate ‘left’ positioned at the left edge of the window and the contents of the page magnified just enough to fit the entire height of the page within the window.

Parameters:

• page (Page) – Page object to display

• left (double) – horizontal coordinate of the left edge of the window

static CreateXYZ(page, left, top, zoom)

Create a new ‘XYZ’ Destination.

The new Destination displays the page designated by ‘page’, with the coordinates (‘left’, ‘top’) positioned at the top-left corner of the window and the contents of the page magnified by the factor ‘zoom’. A null value for any of the parameters ‘left’, ‘top’, or ‘zoom’ specifies that the current value of that parameter is to be retained unchanged. A ‘zoom’ value of 0 has the same meaning as a null value. the page within the window in the other dimension.

Parameters:

• page (Page) – Page object to display

• left (double) – horizontal coordinate of the left edge of the window

• top (double) – vertical coordinate of the top edge of the window

• zoom (double) – amount to zoom the page by

GetExplicitDestObj()

Return type:

Obj

Returns:

the explicit destination SDF/Cos object. This is always an Array as shown in Table 8.2 in PDF Reference Manual.

Raises:

An Exception is thrown if this is not a valid Destination.

GetFitType()

Return type:

int

Returns:

destination’s FitType.

Raises:

An Exception is thrown if this is not a valid Destination.

GetPage()

Return type:

Page

Returns:

the Page that this destination refers to.

Raises:

An Exception is thrown if this is not a valid Destination.

GetSDFObj()

Return type:

Obj

Returns:

the object to the underlying SDF/Cos object. The returned SDF/Cos object is an explicit destination (i.e. the Obj is either an array defining the destination, using the syntax shown in Table 8.2 in PDF Reference Manual), or a dictionary with a ‘D’ entry whose value is such an array. The latter form allows additional attributes to be associated with the destination

IsValid()

Return type:

boolean

Returns:

True if this is a valid Destination and can be resolved, false otherwise.

Notes: If this method returns false the underlying SDF/Cos object is null and the Action object should be treated as null as well.

SetPage(page)

Modify the destination so that it refers to the new ‘page’ as the destination page.

Parameters:

page (Page) – The new page associated with this Destination.

Raises:

An Exception is thrown if this is not a valid Destination.

e_Fit = 1

e_FitB = 5

e_FitBH = 6

e_FitBV = 7

e_FitH = 2

e_FitR = 4

e_FitV = 3

e_XYZ = 0

property mp_dest

property thisown

The membership flag

apryse_sdk.Destination_CreateFit(page)

Create a new ‘Fit’ Destination.

The new Destination displays the page designated by ‘page’, with its contents magnified just enough to fit the entire page within the window both horizontally and vertically. If the required horizontal and vertical magnification factors are different, use the smaller of the two, centering the page within the window in the other dimension.

Parameters:

page (Page) – Page object to display

apryse_sdk.Destination_CreateFitB(page)

Create a new ‘FitB’ Destination.

The new Destination displays the page designated by ‘page’, with its contents magnified just enough to fit its bounding box entirely within the window both horizontally and vertically. If the required horizontal and vertical magnification factors are different, use the smaller of the two, centering the bounding box within the window in the other dimension.

Parameters:

page (Page) – Page object to display

apryse_sdk.Destination_CreateFitBH(page, top)

Create a new ‘FitBH’ Destination.

The new Destination displays the page designated by ‘page’, with the vertical coordinate ‘top’ positioned at the top edge of the window and the contents of the page magnified just enough to fit the entire width of its bounding box within the window.

Parameters:

• page (Page) – Page object to display

• top (double) – vertical coordinate of the top edge of the window

apryse_sdk.Destination_CreateFitBV(page, left)

Create a new ‘FitBV’ Destination.

The new Destination displays Display the page designated by ‘page’, with the horizontal coordinate ‘left’ positioned at the left edge of the window and the contents of the page magnified just enough to fit the entire height of its bounding box within the window.

Parameters:

• page (Page) – Page object to display

• left (double) – horizontal coordinate of the left edge of the window

apryse_sdk.Destination_CreateFitH(page, top)

Create a new ‘FitH’ Destination.

The new Destination displays the page designated by ‘page’, with the vertical coordinate ‘top’ positioned at the top edge of the window and the contents of the page magnified just enough to fit the entire width of the page within the window.

Parameters:

• page (Page) – Page object to display

• top (double) – vertical coordinate of the top edge of the window

apryse_sdk.Destination_CreateFitR(page, left, bottom, right, top)

Create a new ‘FitR’ Destination.

The new Destination displays the page designated by ‘page’, with its contents magnified just enough to fit the rectangle specified by the coordinates ‘left’, ‘bottom’, ‘right’, and ‘top’ entirely within the window both horizontally and vertically. If the required horizontal and vertical magnification factors are different, use the smaller of the two, centering the rectangle within the window in the other dimension.

Parameters:

• page (Page) – Page object to display

• left (double) – horizontal coordinate of the left edge of the window

• bottom (double) – vertical coordinate of the bottom edge of the window

• right (double) – horizontal coordinate of the right edge of the window

• top (double) – vertical coordinate of the top edge of the window

apryse_sdk.Destination_CreateFitV(page, left)

Create a new ‘FitV’ Destination.

The new Destination displays the page designated by ‘page’, with the horizontal coordinate ‘left’ positioned at the left edge of the window and the contents of the page magnified just enough to fit the entire height of the page within the window.

Parameters:

• page (Page) – Page object to display

• left (double) – horizontal coordinate of the left edge of the window

apryse_sdk.Destination_CreateXYZ(page, left, top, zoom)

Create a new ‘XYZ’ Destination.

The new Destination displays the page designated by ‘page’, with the coordinates (‘left’, ‘top’) positioned at the top-left corner of the window and the contents of the page magnified by the factor ‘zoom’. A null value for any of the parameters ‘left’, ‘top’, or ‘zoom’ specifies that the current value of that parameter is to be retained unchanged. A ‘zoom’ value of 0 has the same meaning as a null value. the page within the window in the other dimension.

Parameters:

• page (Page) – Page object to display

• left (double) – horizontal coordinate of the left edge of the window

• top (double) – vertical coordinate of the top edge of the window

• zoom (double) – amount to zoom the page by

class apryse_sdk.DictIterator(args)

Bases: object

DictIterator is used to traverse key/value pairs in a dictionary. For example a DictIterator can be used to print out all the entries in a given Obj dictionary as follows:

DictIterator itr = dict.GetDictIterator();
while (itr.HasNext()) {
    Obj key = itr.Key();
           cout < key.GetName() < endl;
    Obj value = itr.Value();
    // ...
    itr.Next()
 }

Destroy()

Frees the native memory of the object.

HasNext()

Return type:

boolean

Returns:

true if the iterator can be successfully advanced to the next element; false if the end collection is reached.

Key()

Return type:

Obj

Returns:

the key of the current dictionary entry.

Next()

Advances the iterator to the next element of the collection.

Value()

Return type:

Obj

Returns:

the value of the current dictionary entry.

property mp_impl

property thisown

The membership flag

class apryse_sdk.DiffOptions

Bases: object

GetAddGroupAnnots()

Gets the value AddGroupAnnots from the options object Whether we should add an annot layer indicating the difference regions

Return type:

boolean

Returns:

a bool, the current value for AddGroupAnnots.

GetBlendMode()

Gets the value BlendMode from the options object How the two colors should be blended.

Return type:

GState::BlendMode

Returns:

a GState::BlendMode, the current value for BlendMode.

GetColorA()

Gets the value ColorA from the options object The difference color for the first page.

Return type:

ColorPt

Returns:

a ColorPt, the current value for ColorA.

GetColorB()

Gets the value ColorB from the options object The difference color for the second page

Return type:

ColorPt

Returns:

a ColorPt, the current value for ColorB.

GetInternalObj()

SetAddGroupAnnots(value)

Sets the value for AddGroupAnnots in the options object Whether we should add an annot layer indicating the difference regions

Parameters:

value: – the new value for AddGroupAnnots

Return type:

DiffOptions

Returns:

this object, for call chaining

SetBlendMode(value)

Sets the value for BlendMode in the options object How the two colors should be blended.

Parameters:

value: – the new value for BlendMode

Return type:

DiffOptions

Returns:

this object, for call chaining

SetColorA(value)

Sets the value for ColorA in the options object The difference color for the first page.

Parameters:

value: – the new value for ColorA

Return type:

DiffOptions

Returns:

this object, for call chaining

SetColorB(value)

Sets the value for ColorB in the options object The difference color for the second page

Parameters:

value: – the new value for ColorB

Return type:

DiffOptions

Returns:

this object, for call chaining

property thisown

The membership flag

class apryse_sdk.DigestAlgorithm

Bases: object

static CalculateDigest(in_digest_algorithm_type, in_message_buf)

Calculates a digest of arbitrary data. Useful during CMS generation custom signing workflows for digesting signedAttributes before sending off for CMS signatureValue generation (e.g. by HSM device or cloud signing platform).

Parameters:

• in_digest_algorithm_type (int) – – the digest algorithm to use

• in_message_buf (std::vector< UChar,std::allocator< UChar > >) – – the message to digest

Return type:

std::vector< UChar,std::allocator< UChar > >

Returns:

a container of bytes corresponding to the digest of the message

static SignDigest(args)

Overload 1:

Sign the digest of arbitrary data with private key in the provided PKCS #12 key file (.pfx). This function is part of the low-level custom signing API, and works with GenerateESSSigningCertPAdESAttribute, GenerateCMSSignedAttributes, and GenerateCMSSignature.

Parameters:

• digest_buf (std::vector< UChar,std::allocator< UChar > >) – – The digest to sign.

• digest_algorithm_type (int) – – The digest algorithm used to generate the digest.

• pkcs12_keyfile_path (string) – – The path to the PKCS #12 keyfile (usually has a .pfx extension) to use for signing.

• pkcs12_password (string) – – The password to use to parse the PKCS #12 keyfile.

Return type:

std::vector< UChar,std::allocator< UChar > >

Returns:

the DER-serialized bytes of the signature.

Overload 2:

Sign the digest of arbitrary data with private key in the provided PKCS #12 key file (.pfx). This function is part of the low-level custom signing API, and works with GenerateESSSigningCertPAdESAttribute, GenerateCMSSignedAttributes, and GenerateCMSSignature.

Parameters:

• digest_buf (std::vector< UChar,std::allocator< UChar > >) – – The digest to sign.

• digest_algorithm_type (int) – – The digest algorithm used to generate the digest.

• pkcs12_buf (std::vector< UChar,std::allocator< UChar > >) – – The buffer containing the PKCS #12 key (as usually stored in .pfx files) to use for signing.

• pkcs12_password (string) – – The password to use to parse the PKCS 12 key.

Return type:

std::vector< UChar,std::allocator< UChar > >

Returns:

the DER-serialized bytes of the signature.

e_RIPEMD160 = 4

e_SHA1 = 0

e_SHA256 = 1

e_SHA384 = 2

e_SHA512 = 3

e_unknown_digest_algorithm = 5

property thisown

The membership flag

apryse_sdk.DigestAlgorithm_CalculateDigest(in_digest_algorithm_type, in_message_buf)

Calculates a digest of arbitrary data. Useful during CMS generation custom signing workflows for digesting signedAttributes before sending off for CMS signatureValue generation (e.g. by HSM device or cloud signing platform).

Parameters:

• in_digest_algorithm_type (int) – – the digest algorithm to use

• in_message_buf (std::vector< UChar,std::allocator< UChar > >) – – the message to digest

Return type:

std::vector< UChar,std::allocator< UChar > >

Returns:

a container of bytes corresponding to the digest of the message

apryse_sdk.DigestAlgorithm_SignDigest(args)

Overload 1:

Sign the digest of arbitrary data with private key in the provided PKCS #12 key file (.pfx). This function is part of the low-level custom signing API, and works with GenerateESSSigningCertPAdESAttribute, GenerateCMSSignedAttributes, and GenerateCMSSignature.

Parameters:

• digest_buf (std::vector< UChar,std::allocator< UChar > >) – – The digest to sign.

• digest_algorithm_type (int) – – The digest algorithm used to generate the digest.

• pkcs12_keyfile_path (string) – – The path to the PKCS #12 keyfile (usually has a .pfx extension) to use for signing.

• pkcs12_password (string) – – The password to use to parse the PKCS #12 keyfile.

Return type:

std::vector< UChar,std::allocator< UChar > >

Returns:

the DER-serialized bytes of the signature.

Overload 2:

Sign the digest of arbitrary data with private key in the provided PKCS #12 key file (.pfx). This function is part of the low-level custom signing API, and works with GenerateESSSigningCertPAdESAttribute, GenerateCMSSignedAttributes, and GenerateCMSSignature.

Parameters:

• digest_buf (std::vector< UChar,std::allocator< UChar > >) – – The digest to sign.

• digest_algorithm_type (int) – – The digest algorithm used to generate the digest.

• pkcs12_buf (std::vector< UChar,std::allocator< UChar > >) – – The buffer containing the PKCS #12 key (as usually stored in .pfx files) to use for signing.

• pkcs12_password (string) – – The password to use to parse the PKCS 12 key.

Return type:

std::vector< UChar,std::allocator< UChar > >

Returns:

the DER-serialized bytes of the signature.

class apryse_sdk.DigitalSignatureField(args)

Bases: object

A class representing a digital signature form field.

CalculateDigest(args)

Calculates the digest of the relevant bytes of the document for this signature field, in order to allow

the caller to perform custom signing/processing. Signature field must first be prepared using one of the non-sign overloads (CreateSigDictForCustomSigning/Certification), and then the document must be saved; after that, this function can be called. The ByteRanges that the most recent save has entered into the signature dictionary within this signature field will be used to calculate the digest.

Parameters:

in_digest_algorithm_type (int) – – the enumerated type of digest algorithm to use for the calculation. The default is SHA-256.

Return type:

std::vector< UChar,std::allocator< UChar > >

Returns:

an array of bytes containing the digest value

CertifyOnNextSave(args)

Overload 1:

Must be called to prepare a signature for certification, which is done afterwards by calling Save. Throws if document already certified. Default document permission level is e_annotating_formfilling_signing_allowed. Throws if signature field already has a digital signature dictionary.

Parameters:

• in_pkcs12_keyfile_path (string) – – The path to the PKCS #12 private keyfile to use to certify this digital signature.

• in_password (string) – – The password to use to parse the PKCS #12 keyfile.

Overload 2:

Must be called to prepare a signature for certification, which is done afterwards by calling Save. Throws if document already certified. Default document permission level is e_annotating_formfilling_signing_allowed. Throws if signature field already has a digital signature dictionary.

Parameters:

• in_pkcs12_buffer (UChar) – – A buffer of bytes containing the PKCS #12 private key certificate store to use to certify this digital signature.

• in_buf_size (int) – – buffer size.

• in_password (string) – – The password to use to parse the PKCS #12 buffer.

CertifyOnNextSaveWithCustomHandler(in_signature_handler_id)

Must be called to prepare a signature for certification, which is done afterwards by calling Save. Throws if document already certified. Default document permission level is e_annotating_formfilling_signing_allowed. Throws if signature field already has a digital signature dictionary.

Parameters:

in_signature_handler_id (int) – – The unique id of the signature handler to use to certify this digital signature.

ClearSignature()

Clears cryptographic signature, if present. Otherwise, does nothing. Do not need to call HasCryptographicSignature before calling this. After clearing, other signatures should still pass validation if saving after clearing was done incrementally. Clears the appearance as well.

CreateSigDictForCustomCertification(in_filter_name, in_subfilter_type, in_contents_size_to_reserve)

Prepares the field for certification without actually performing certification.

Useful for custom signing workflows. It is not necessary to call HasCryptographicSignature before calling this function.

Parameters:

• in_filter_name (string) – the Filter name to use, representing the name of the signature handler that will be used to sign and verify the signature (e.g. Adobe.PPKLite)

• in_subfilter_type (int) – the SubFilter name to use, representing an interoperable signature type identifier for third-party verification (e.g. adbe.pkcs7.detached, ETSI.CAdES.detached, etc.)

• in_contents_size_to_reserve (int) – The size of the empty Contents entry to create. For security reasons, set the contents size to a value greater than but as close as possible to the size you expect your final signature to be.

CreateSigDictForCustomSigning(in_filter_name, in_subfilter_type, in_contents_size_to_reserve)

Prepares the field for approval signing without actually performing signing.

Useful for custom signing workflows. It is not necessary to call HasCryptographicSignature before calling this function.

Parameters:

• in_filter_name (string) – the Filter name to use, representing the name of the signature handler that will be used to sign and verify the signature (e.g. Adobe.PPKLite)

• in_subfilter_type (int) – the SubFilter name to use, representing an interoperable signature type identifier for third-party verification (e.g. adbe.pkcs7.detached, ETSI.CAdES.detached, etc.)

• in_contents_size_to_reserve (int) – The size of the empty Contents entry to create. For security reasons, set the contents size to a value greater than but as close as possible to the size you expect your final signature to be.

EnableLTVOfflineVerification(in_verification_result)

Given a successful verification result that required online information to verify trust (trust verification must have been enabled and successful during the verification), embeds data into the PDF document that allows the signature to be verified offline. (This is accomplished using DSS and VRI dictionaries.) When this operation is successfully completed, one of the two components of secure long term validation (LTV) will be in place. The other necessary component of secure long term validation is to make sure to timestamp the document appropriately while the signature is still verifiable to maintain a chain of unexpired secure timestamps attesting to the integrity of the document. The verifiability of the signature should thereafter be maintainable in such a fashion despite any possible certificate expiry, algorithm compromise, or key compromise that would have otherwise rendered it invalid if it were to be verified using a time in the future rather than a securely-signed timestamp-derived time nearer the time of signing (at which which the signature was verifiable without extra data). This function, if given a good verification result, is also capable of making timestamp (DocTimeStamp ETSI.RFC3161) signatures LTV-enabled, which is necessary to do first when you intend to add another timestamp around an already-timestamped document to extend or enhance its verifiability (as described above), as per the PDF 2.0 and ETSI TS 102 778-4 (PAdES Level 4) specifications.

Parameters:

in_verification_result (VerificationResult) – – a successful verification result containing a successful TrustVerificationResult

Return type:

boolean

Returns:

a boolean status that reflects whether offline verification information was added successfully

Notes: It is necessary to save the document incrementally after this function completes successfully in order to actually write the LTV data into the document.

static GenerateCMSSignature(in_signer_cert, in_chain_certs_list, in_digest_algorithm_oid, in_signature_algorithm_oid, in_signature_value_buf, in_signedattributes_buf)

Low-level function belonging to custom-signing APIs. Using low-level inputs that permit incorporation of remote key usage (cloud keystore, Hardware Security Module (HSM) device, etc.), generates bytes representing a Cryptographic Message Syntax (CMS)-format signature encoded in DER. The resulting data can be passed to SaveCustomSignature.

Parameters:

• in_signer_cert (X509Certificate) – – the X509 public-key certificate of the signature’s signer (mathematically associated with private key used)

• in_chain_certs_list (std::vector< Crypto::X509Certificate,std::allocator< Crypto::X509Certificate > >) – – the intermediate and root certificates to include in the CMS to allow verifiers to establish the chain/path of trust

• in_digest_algorithm_oid (ObjectIdentifier) – – the OID of the digest algorithm used, for embedding in the CMS

• in_signature_algorithm_oid (ObjectIdentifier) – – the OID of the signature algorithm used, for embedding in the CMS

• in_signature_value_buf (std::vector< UChar,std::allocator< UChar > >) – – a buffer containing the signature value to embed in the CMS

• in_signedattributes_buf (std::vector< UChar,std::allocator< UChar > >) – – a buffer containing signedAttributes for embedding into the CMS (must exactly match those used when creating signature value)

Return type:

std::vector< UChar,std::allocator< UChar > >

Returns:

finished CMS data for embedding into the document using SaveCustomSignature

static GenerateCMSSignedAttributes(args)

Low-level function belonging to custom-signing APIs. Creates the signedAttributes component of Cryptographic Message Syntax (CMS). The result of this function can then be encrypted by a remote private key (cloud service, Hardware Security Module (HSM) device, etc.), using some external API that returns the bytes of a not-already-CMS-embedded signature value (e.g. RSA PKCS #1 v1.5 format). Following that, CMS generation can be performed using GenerateCMSSignature, after which the resulting signature can be inserted into a resulting signed version of the PDF document using the PDFDoc function SaveCustomSignature.

Parameters:

• in_digest_buf (std::vector< UChar,std::allocator< UChar > >) – – a buffer containing the digest of the document within ByteRanges of this DigitalSignatureField (see CalculateDigest)

• in_custom_signedattributes_buf (std::vector< UChar,std::allocator< UChar > >) – – a buffer containing any optional custom BER-encoded signedAttributes to add, including potentially the PAdES one (see GenerateESSSigningCertPAdESAttribute). (Do not place an ASN.1ructed type around all of the attributes.) Do not pass any of the normal attributes (content type or message digest) as custom attributes because otherwise they will be duplicated.

Return type:

std::vector< UChar,std::allocator< UChar > >

Returns:

the BER-encoded bytes of the future signedAttrs component of a CMS signature, with no surroundingructed type

GenerateContentsWithEmbeddedTimestamp(in_timestamping_config, in_timestamp_response_verification_options)

Contacts a remote timestamp authority over network, sends CMS digest, receives and verifies timestamp token, combines the timestamp token and the data of an existing CMS-type (adbe.pkcs7.detached or ETSI.CAdES.detached subfilter) main document signature, and then returns that data to the user. At least one signing time, whether “M” (see SetSigDictTimeOfSigning) or a secure embedded timestamp, is required to be added in order to create a PAdES signature.

Notes: This function does not insert the final CMS-type document signature into the document. You must retrieve it from the result using GetData and then pass that to PDFDoc SaveCustomSignature.

Parameters:

• in_timestamping_config (TimestampingConfiguration) – – Configuration options to store for timestamping. These will include various items related to contacting a timestamping authority. Incorrect configuration will result in an exception being thrown. The usability of a combination of a TimestampingConfiguration and VerificationOptions can be checked ahead of time to prevent exceptions by calling TestConfiguration on TimestampingConfiguration and passing VerificationOptions.

• in_timestamp_response_verification_options (VerificationOptions) – – Options for the timestamp response verification step (which is required by RFC 3161 to be done as part of timestamping). These response verification options should include the root certificate of the timestamp authority, so that the trust status of the timestamp signature can be verified. The options that should be passed are the same ones that one expects the timestamp to be verifiable with in the future (once it is embedded in the document), except the response verification requires online revocation information whereas the later verification may not (depending on whether LTV offline verification information for the embedded timestamp gets embedded into the document by that time). The timestamp response verification step makes sure that (a) the timestamp response has a success status, which is the only time that this is verified in the entire workflow, which prevents embedding an unsuccessful response; (b) that it digests the main signature digest correctly and is otherwise generally verifiable; and (c) that the nonce is correct (which is the only time that this is verifiable in the entire workflow) to prevent replay attacks (if it was not requested in the TimestampingConfiguration that the nonce mechanism should be disabled).

Return type:

TimestampingResult

Returns:

The result of the timestamp request, including the final document signature as DER-encoded CMS with a timestamp embedded

static GenerateESSSigningCertPAdESAttribute(in_signer_cert, in_digest_algorithm_type)

Low-level optional function belonging to custom-signing APIs allowing creation of PAdES signatures with key elsewhere, allowing CMS to be generated automatically later. Represents one the components of the functionality of SignDigest which are not key-related. Creates the necessary attribute for a PAdES signature (ETSI.CAdES.detached subfilter type). The result of this function can be passed as a contiguous part of the custom attributes buffer parameter of GenerateCMSSignedAttributes. At least one signing time, whether “M” (see SetSigDictTimeOfSigning) or a secure embedded timestamp (see GenerateContentsWithEmbeddedTimestamp), is also required to be added in order to create a PAdES signature.

The result will be either the BER-serialized bytes of an ESS_signing_cert or ESS_signing_cert_V2 CMS Attribute (an ASN.1 SEQUENCE containing the correct OID and ESSCertID or ESSCertIDv2), as is appropriate, depending on what digest algorithm type is provided (see RFC 5035).

Parameters:

• in_signer_cert (X509Certificate) – – the X509 public-key certificate of the signature’s signer (mathematically associated with private key to be used)

• in_digest_algorithm_type (int) – – the digest algorithm to be used

Return type:

std::vector< UChar,std::allocator< UChar > >

Returns:

the BER-serialized bytes of an ESS_signing_cert or ESS_signing_cert_V2 CMS attribute

GetByteRanges()

Retrieves the ranges of byte indices within the document over which this signature is intended to apply/be verifiable.

Return type:

std::vector< Common::ByteRange,std::allocator< Common::ByteRange > >

Returns:

a container of byte range objects

Notes: This function does not verify that the signature is valid over its byte ranges. It merely returns them. This can be useful when a document consists of multiple incremental revisions, the latter of which may or may not have been signed, for telling which revisions were actually signed by which signature. The outputs of this function can also be used to truncate the document at the end of a signed byte range, in order that the signed document revision may be retrieved from a document with later incremental revisions. Of course, to be certain that the signature is valid, it must also then be verified using the verification API. Also, the caller is responsible for making sure that the byte ranges returned from this function actually make sense (i.e. fit inside the document).

GetCert(in_index)

Gets a certificate in the certificate chain (Cert entry) of the digital signature dictionary by index. Throws if Cert is not Array or String, throws if index is out of range and Cert is Array, throws if index is > 1 and Cert is string, otherwise retrieves the certificate. Only to be used for old-style adbe.x509.rsa_sha1 signatures; for other signatures, use CMS getter functions instead.

Parameters:

in_index (int) – – An integral index which must be greater than 0 and less than the cert count as retrieved using GetCertCount.

Return type:

std::vector< UChar,std::allocator< UChar > >

Returns:

A vector of bytes containing the certificate at the index. Returns empty vector if Cert is missing.

GetCertCount()

Gets number of certificates in certificate chain (Cert entry of digital signature dictionary). Must call HasCryptographicSignature first and use it to check whether the signature is signed. Only to be used for old-style adbe.x509.rsa_sha1 signatures; for other signatures, use CMS getter functions instead.

Return type:

int

Returns:

An integer value - the number of certificates in the Cert entry of the digital signature dictionary.

GetCertPathsFromCMS()

Retrieves allructible certificate paths from an adbe.pkcs7.detached or ETSI.CAdES.detached digital signature.

The signer will always be returned if the signature is CMS-based and not corrupt. Must only be called on signed adbe.pkcs7.detached signatures. The order of the certificates in each of the paths returned is as follows: the signer will be first, and issuers come after it in order of the issuer of the previous certificate. The default behaviour is to return a sub-path for each marginal issuer in a max-length path.

Return type:

std::vector< std::vector< Crypto::X509Certificate,std::allocator< Crypto::X509Certificate > >,std::allocator< std::vector< Crypto::X509Certificate,std::allocator< Crypto::X509Certificate > > > >

Returns:

a container of X509Certificate objects

Notes: This function does not verify the paths. It merely extracts certificates andructs paths. This function only works when the build has support for verification-related APIs.

GetContactInfo()

Should not be called when SubFilter is ETSI.RFC3161 (i.e. on a DocTimeStamp). Returns the contact information of the signer from the digital signature dictionary. Must call HasCryptographicSignature first and use it to check whether the signature is signed.

Return type:

string

Returns:

A unicode string containing the contact information of the signer from within the digital signature dictionary. Empty if ContactInfo entry not present.

GetDocumentPermissions()

If HasCryptographicSignature, returns most restrictive permissions found in any reference entries in this digital signature. Returns Lock-resident (i.e. tentative) permissions otherwise. Throws if invalid permission value is found.

Return type:

int

Returns:

An enumeration value representing the level of restrictions (potentially) placed on the document by this signature.

GetLocation()

Should not be called when SubFilter is ETSI.RFC3161 (i.e. on a DocTimeStamp). Returns the Location of the signature from the digital signature dictionary. Must call HasCryptographicSignature first and use it to check whether the signature is signed.

Return type:

string

Returns:

A unicode string containing the signing location from within the digital signature dictionary. Empty if Location entry not present.

GetLockedFields()

Returns the fully-qualified names of all fields locked by this signature using the field permissions feature. Retrieves from the digital signature dictionary if the form field HasCryptographicSignature. Otherwise, retrieves from the Lock entry of the digital signature form field. Result is invalidated by any field additions or removals. Does not take document permissions restrictions into account.

Return type:

std::vector< std::string,std::allocator< std::string > >

Returns:

A vector of UStrings representing the fully-qualified names of all fields locked by this signature.

GetReason()

Should not be called when SubFilter is ETSI.RFC3161 (i.e. on a DocTimeStamp). Returns the Reason for the signature from the digital signature dictionary. Must call HasCryptographicSignature first and use it to check whether the signature is signed.

Return type:

string

Returns:

A unicode string containing the reason for the signature from within the digital signature dictionary. Empty if Reason entry not present.

GetSDFObj()

Retrieves the SDF Obj of the digital signature field.

Return type:

Obj

Returns:

the underlying SDF/Cos object.

GetSignatureName()

Should not be called when SubFilter is ETSI.RFC3161 (i.e. on a DocTimeStamp). Returns the name of the signer of the signature from the digital signature dictionary. Must call HasCryptographicSignature first and use it to check whether the signature is signed.

Return type:

string

Returns:

A unicode string containing the name of the signer from within the digital signature dictionary. Empty if Name entry not present.

GetSignerCertFromCMS()

Returns the signing certificate. Must only be called on signed adbe.pkcs7.detached or ETSI.CAdES.detached signatures.

Return type:

X509Certificate

Returns:

An X509Certificate object.

Notes: This function does not verify the signature. It merely extracts the claimed signing certificate. This function only works when the build has support for verification-related APIs.

GetSigningTime()

Should not be called when SubFilter is ETSI.RFC3161 (i.e. on a DocTimeStamp). Returns the “M” entry from the digital signature dictionary, which represents the signing date/time. Must call HasCryptographicSignature first and use it to check whether the signature is signed.

Return type:

Date

Returns:

A PDF::Date object holding the signing date/time from within the digital signature dictionary. Returns a default-constructed PDF::Date if no date is present.

GetSubFilter()

Returns the SubFilter type of the digital signature. Specification says that one must check the SubFilter before using various getters. Must call HasCryptographicSignature first and use it to check whether the signature is signed.

Return type:

int

Returns:

An enumeration describing what the SubFilter of the digital signature is from within the digital signature dictionary.

HasCryptographicSignature()

Returns whether the digital signature field has been cryptographically signed. Checks whether there is a digital signature dictionary in the field and whether it has a Contents entry. Must be called before using various digital signature dictionary-related functions. Does not check validity - will return true even if a valid hash has not yet been generated (which will be the case after [Certify/Sign]OnNextSave[WithCustomHandler] has been called on the signature but even before Save is called on the document).

Return type:

boolean

Returns:

A boolean value representing whether the digital signature field has a digital signature dictionary with a Contents entry.

HasVisibleAppearance()

Returns whether the field has a visible appearance. Can be called without checking HasCryptographicSignature first, since it operates on the surrounding Field dictionary, not the “V” entry (i.e. digital signature dictionary). Performs the zero-width+height check, the Hidden bit check, and the NoView bit check as described by the PDF 2.0 specification, section 12.7.5.5 “Signature fields”.

Return type:

boolean

Returns:

A boolean representing whether or not the signature field has a visible signature.

IsCertification()

Returns whether or not this signature is a certification.

Return type:

boolean

Returns:

a boolean value representing whether or not this signature is a certification.

IsLockedByDigitalSignature()

Returns whether this digital signature field is locked against modifications by any digital signatures. Can be called when this field is unsigned.

Return type:

boolean

Returns:

A boolean representing whether this digital signature field is locked against modifications by any digital signatures in the document.

SetContactInfo(in_contact_info)

Should not be called when SubFilter is ETSI.RFC3161 (i.e. on a DocTimeStamp). Sets the ContactInfo entry in the digital signature dictionary. Must create a digital signature dictionary first using [Certify/Sign]OnNextSave[WithCustomHandler]. If this function is called on a digital signature field that has already been cryptographically signed with a valid hash, the hash will no longer be valid, so do not call Save (to sign/create the hash) until after you call this function, if you need to call this function in the first place. Essentially, call this function after [Certify/Sign]OnNextSave[WithCustomHandler] and before Save.

Parameters:

in_contact_info (string) – – A string containing the ContactInfo to be set.

static SetDigSigLogFilename(filename)

Sets the digital signature logging filename, and enables the logging. This function is expected to be called only once. Subsequent calls to the function will have no effect.

Parameters:

filename (string) – The name (and path) of the log file.

Return type:

boolean

Returns:

True if this operation was successful and false if it failed because the logging process has already started.

SetDocumentPermissions(in_perms)

Sets the document locking permission level for this digital signature field. Call only on unsigned signatures, otherwise a valid hash will be invalidated.

Parameters:

in_perms (int) – – An enumerated value representing the document locking permission level to set.

SetFieldPermissions(args)

Tentatively sets which fields are to be locked by this digital signature upon signing. It is not necessary to call HasCryptographicSignature before using this function. Throws if non-empty array of field names is passed along with FieldPermissions Action == e_lock_all.

Parameters:

• in_action (int) – – An enumerated value representing which sort of field locking should be done. Options are All (lock all fields), Include (lock listed fields), and Exclude (lock all fields except listed fields).

• in_field_names (std::vector< std::string,std::allocator< std::string > >) – – A list of field names; can be empty (and must be empty, if Action is set to All). Empty by default.

SetLocation(in_location)

Should not be called when SubFilter is ETSI.RFC3161 (i.e. on a DocTimeStamp). Sets the Location entry in the digital signature dictionary. Must create a digital signature dictionary first using [Certify/Sign]OnNextSave[WithCustomHandler]. If this function is called on a digital signature field that has already been cryptographically signed with a valid hash, the hash will no longer be valid, so do not call Save (to sign/create the hash) until after you call this function, if you need to call this function in the first place. Essentially, call this function after [Certify/Sign]OnNextSave[WithCustomHandler] and before Save.

Parameters:

in_location (string) – – A string containing the Location to be set.

SetPreferredDigestAlgorithm(in_digest_algorithm_type, in_make_mandatory=True)

Sets the preferred digest algorithm to use when signing this field. This is done by setting DigestMethod

in the Seed Value dictionary. This function can be called before a signature field is even prepared for signing.

Parameters:

• in_digest_algorithm_type (int) – – the digest algorithm to use

• in_make_mandatory (boolean) – – whether to tell signing software to give up if the preferred algorithm is unsupported. Default value for this parameter is true.

SetReason(in_reason)

Should not be called when SubFilter is ETSI.RFC3161 (i.e. on a DocTimeStamp). Sets the Reason entry in the digital signature dictionary. Must create a digital signature dictionary first using [Certify/Sign]OnNextSave[WithCustomHandler]. If this function is called on a digital signature field that has already been cryptographically signed with a valid hash, the hash will no longer be valid, so do not call Save (to sign/create the hash) until after you call this function, if you need to call this function in the first place. Essentially, call this function after [Certify/Sign]OnNextSave[WithCustomHandler] and before Save.

Parameters:

in_reason (string) – – A string containing the Reason to be set.

SetSigDictTimeOfSigning(in_date)

Adds the “M” key and value, representing the PDF-time-of-signing (not to be confused with

embedded timestamps, DocTimeStamps, or CMS signing time), to the digital signature dictionary. The digital signature field must have been prepared for signing first. This function should only be used if no secure embedded timestamping support is available from your signing provider. Useful for custom signing workflows, where signing time is not set automatically by the Apryse SDK, unlike in the usual standard handler signing workflow. A secure embedded timestamp can also be added later and should override this “M” date entry when the signature is read by signature-verifying PDF processor applications. At least one signing time, whether “M” or a secure embedded timestamp (see GenerateContentsWithEmbeddedTimestamp), is required to be added in order to create a PAdES signature.

Parameters:

in_date (Date) – the PDF Date datetime value to set

static SignDigest(args)

Overload 1:

Returns a CMS detached signature incorporating a digest that is provided using the provided PKCS #12 key file (.pfx). This function is part of the custom signing API, but cannot be used for workflows where the key is not in PFX format or when the signature comes from a source that cannot generate CMS signatures (e.g. Hardware Security Modules (HSM) devices, cloud signing services). In such cases, the low-level parts of the custom signing API should be used instead of this function (e.g. GenerateESSSigningCertPAdESAttribute, GenerateCMSSignedAttributes, GenerateCMSSignature). This function is a shortcut for situations in which use of more low-level custom signing functions is unnecessary. Therefore, this function will generate necessary CMS components, such as signedAttrs, internally. Notes: This function does not change the DigitalSignatureField. Call SaveCustomSignature to write a signature to its PDFDoc.

Parameters:

• in_digest (std::vector< UChar,std::allocator< UChar > >) – – the document digest value to use

• in_pkcs12_keyfile_path (string) – – the path to the PKCS #12 key file (usually has a .pfx extension) to use for signing

• in_keyfile_password (string) – – the password to use to decrypt the PKCS #12 key file

• in_pades_mode (boolean) – – whether to create a PAdES-type signature (PDF Advanced Electronic Signatures standards)

• in_digest_algorithm_type (int) – – the identifier to use to write the digest algorithm

Return type:

std::vector< UChar,std::allocator< UChar > >

Returns:

the DER-serialized bytes of a CMS detached signature (CMS ContentInfo)

Overload 2:

Returns a CMS detached signature incorporating a digest that is provided using the provided PKCS #12 key buffer (.pfx). This function is part of the custom signing API, but cannot be used for workflows where the key is not in PFX format or when the signature comes from a source that cannot generate CMS signatures (e.g. Hardware Security Modules (HSM) devices, cloud signing services). In such cases, the low-level parts of the custom signing API should be used instead of this function (e.g. GenerateESSSigningCertPAdESAttribute, GenerateCMSSignedAttributes, GenerateCMSSignature). This function is a shortcut for situations in which use of more low-level custom signing functions is unnecessary. Therefore, this function will generate necessary CMS components, such as signedAttrs, internally. Notes: This function does not change the DigitalSignatureField. Call SaveCustomSignature to write a signature to its PDFDoc.

Parameters:

• in_digest (std::vector< UChar,std::allocator< UChar > >) – – the document digest value to use

• in_pkcs12_buffer (std::vector< UChar,std::allocator< UChar > >) – – a buffer containing the PKCS #12 key (as usually stored in .pfx files) to use for signing

• in_keyfile_password (string) – – the password to use to decrypt the PKCS #12 key file data in the buffer

• in_pades_mode (boolean) – – whether to create a PAdES-type signature (PDF Advanced Electronic Signatures standards)

• in_digest_algorithm_type (int) – – the identifier to use to write the digest algorithm

Return type:

std::vector< UChar,std::allocator< UChar > >

Returns:

the DER-serialized bytes of a CMS detached signature (CMS ContentInfo)

SignOnNextSave(args)

Overload 1:

Must be called to prepare a signature for signing, which is done afterwards by calling Save. Cannot sign two signatures during one save (throws). Default document permission level is e_annotating_formfilling_signing_allowed. Throws if signature field already has a digital signature dictionary.

Parameters:

• in_pkcs12_keyfile_path (string) – – The path to the PKCS #12 private keyfile to use to sign this digital signature.

• in_password (string) – – The password to use to parse the PKCS #12 keyfile.

Overload 2:

Must be called to prepare a signature for signing, which is done afterwards by calling Save. Cannot sign two signatures during one save (throws). Default document permission level is e_annotating_formfilling_signing_allowed. Throws if signature field already has a digital signature dictionary.

Parameters:

• in_pkcs12_buffer (UChar) – – A buffer of bytes containing the PKCS #12 private key certificate store to use to sign this digital signature.

• in_buf_size (int) – – buffer size.

• in_password (string) – – The password to use to parse the PKCS #12 buffer.

SignOnNextSaveWithCustomHandler(in_signature_handler_id)

Must be called to prepare a signature for signing, which is done afterwards by calling Save. Cannot sign two signatures during one save (throws). Default document permission level is e_annotating_formfilling_signing_allowed. Throws if signature field already has a digital signature dictionary.

Parameters:

in_signature_handler_id (int) – – The unique id of the signature handler to use to sign this digital signature.

TimestampOnNextSave(in_timestamping_config, in_timestamp_response_verification_options)

Must be called to prepare a secure PDF-embedded timestamp signature (RFC 3161

DocTimeStamp) for signing, which is done afterwards by calling Save on the document with an e_incremental flag. Throws if document is locked by other signatures, if signature is already signed, or if another signature has already been prepared for signing on the next save (because only one signing operation can be done per incremental save). Default document permission level is e_annotating_formfilling_signing_allowed.

Parameters:

• in_timestamping_config (TimestampingConfiguration) – – Configuration options to store for timestamping. These will include various items related to contacting a timestamping authority. Incorrect configuration will result in document Save throwing an exception. The usability of a combination of a TimestampingConfiguration and VerificationOptions can be checked ahead of time to prevent exceptions by calling TestConfiguration on TimestampingConfiguration and passing VerificationOptions.

• in_timestamp_response_verification_options (VerificationOptions) – – Options for the timestamp response verification step (which is required by RFC 3161 to be done as part of timestamping). These response verification options should include the root certificate of the timestamp authority, so that the trust status of the timestamp signature can be verified. The options that should be passed are the same ones that one expects the timestamp to be verifiable with in the future (once it is embedded in the document), except the response verification requires online revocation information whereas the later verification may not (depending on whether LTV offline verification information for the timestamp signature gets embedded into the document by that time). The timestamp response verification step makes sure that (a) the timestamp response has a success status, which is the only time that this is verified in the entire workflow, which prevents embedding an unsuccessful response; (b) that it digests the document correctly and is otherwise generally verifiable; and (c) that the nonce is correct (which is the only time that this is verifiable in the entire workflow) to prevent replay attacks (if it was not requested in the TimestampingConfiguration that the nonce mechanism should be disabled).

Notes: A failure in timestamp response verification will result in document Save throwing an exception. It is recommended to use TimestampingConfiguration.TestConfiguration with the VerificationOptions ahead of time to avoid this.

UseSubFilter(in_subfilter_type, in_make_mandatory=True)

Sets the requested SubFilter value (which identifies a signature type) as the only one to use during future signing, overwriting all such previous settings. It is not necessary to call HasCryptographicSignature before calling this function. For example, this function can be used to switch to PAdES signing mode.

Parameters:

• in_subfilter_type (int) – – The SubFilter type to set.

• in_make_mandatory (boolean) – – Whether to make usage of this SubFilter mandatory for future signing applications. Default value for this parameter is true.

Verify(in_opts)

Verifies this cryptographic digital signature in the manner specified by the VerificationOptions.

Parameters:

in_opts (VerificationOptions) – – The options specifying how to do the verification.

Return type:

VerificationResult

Returns:

A VerificationResult object containing various information about the verifiability of the cryptographic digital signature.

e_ETSI_CAdES_detached = 3

e_ETSI_RFC3161 = 4

e_absent = 6

e_adbe_pkcs7_detached = 1

e_adbe_pkcs7_sha1 = 2

e_adbe_x509_rsa_sha1 = 0

e_annotating_formfilling_signing_allowed = 3

e_exclude = 2

e_formfilling_signing_allowed = 2

e_include = 1

e_lock_all = 0

e_no_changes_allowed = 1

e_unknown = 5

e_unrestricted = 4

property m_impl

property thisown

The membership flag

class apryse_sdk.DigitalSignatureFieldIterator(args)

Bases: object

Supports a simple iteration over a generic collection.

Current()

Note: HasNext() must be true before calling Current()

Return type:

DigitalSignatureField

Returns:

the current element in the collection

Destroy()

Frees the native memory of the object.

HasNext()

Return type:

boolean

Returns:

true if the iterator can be successfully advanced to the next element; false if the iterator is no longer valid.

Next()

Note: HasNext() must be true before calling Next() Advances the iterator to the next element of the collection.

property mp_impl

property thisown

The membership flag

apryse_sdk.DigitalSignatureField_GenerateCMSSignature(in_signer_cert, in_chain_certs_list, in_digest_algorithm_oid, in_signature_algorithm_oid, in_signature_value_buf, in_signedattributes_buf)

Low-level function belonging to custom-signing APIs. Using low-level inputs that permit incorporation of remote key usage (cloud keystore, Hardware Security Module (HSM) device, etc.), generates bytes representing a Cryptographic Message Syntax (CMS)-format signature encoded in DER. The resulting data can be passed to SaveCustomSignature.

Parameters:

• in_signer_cert (X509Certificate) – – the X509 public-key certificate of the signature’s signer (mathematically associated with private key used)

• in_chain_certs_list (std::vector< Crypto::X509Certificate,std::allocator< Crypto::X509Certificate > >) – – the intermediate and root certificates to include in the CMS to allow verifiers to establish the chain/path of trust

• in_digest_algorithm_oid (ObjectIdentifier) – – the OID of the digest algorithm used, for embedding in the CMS

• in_signature_algorithm_oid (ObjectIdentifier) – – the OID of the signature algorithm used, for embedding in the CMS

• in_signature_value_buf (std::vector< UChar,std::allocator< UChar > >) – – a buffer containing the signature value to embed in the CMS

• in_signedattributes_buf (std::vector< UChar,std::allocator< UChar > >) – – a buffer containing signedAttributes for embedding into the CMS (must exactly match those used when creating signature value)

Return type:

std::vector< UChar,std::allocator< UChar > >

Returns:

finished CMS data for embedding into the document using SaveCustomSignature

apryse_sdk.DigitalSignatureField_GenerateCMSSignedAttributes(args)

Low-level function belonging to custom-signing APIs. Creates the signedAttributes component of Cryptographic Message Syntax (CMS). The result of this function can then be encrypted by a remote private key (cloud service, Hardware Security Module (HSM) device, etc.), using some external API that returns the bytes of a not-already-CMS-embedded signature value (e.g. RSA PKCS #1 v1.5 format). Following that, CMS generation can be performed using GenerateCMSSignature, after which the resulting signature can be inserted into a resulting signed version of the PDF document using the PDFDoc function SaveCustomSignature.

Parameters:

• in_digest_buf (std::vector< UChar,std::allocator< UChar > >) – – a buffer containing the digest of the document within ByteRanges of this DigitalSignatureField (see CalculateDigest)

• in_custom_signedattributes_buf (std::vector< UChar,std::allocator< UChar > >) – – a buffer containing any optional custom BER-encoded signedAttributes to add, including potentially the PAdES one (see GenerateESSSigningCertPAdESAttribute). (Do not place an ASN.1ructed type around all of the attributes.) Do not pass any of the normal attributes (content type or message digest) as custom attributes because otherwise they will be duplicated.

Return type:

std::vector< UChar,std::allocator< UChar > >

Returns:

the BER-encoded bytes of the future signedAttrs component of a CMS signature, with no surroundingructed type

apryse_sdk.DigitalSignatureField_GenerateESSSigningCertPAdESAttribute(in_signer_cert, in_digest_algorithm_type)

Low-level optional function belonging to custom-signing APIs allowing creation of PAdES signatures with key elsewhere, allowing CMS to be generated automatically later. Represents one the components of the functionality of SignDigest which are not key-related. Creates the necessary attribute for a PAdES signature (ETSI.CAdES.detached subfilter type). The result of this function can be passed as a contiguous part of the custom attributes buffer parameter of GenerateCMSSignedAttributes. At least one signing time, whether “M” (see SetSigDictTimeOfSigning) or a secure embedded timestamp (see GenerateContentsWithEmbeddedTimestamp), is also required to be added in order to create a PAdES signature.

The result will be either the BER-serialized bytes of an ESS_signing_cert or ESS_signing_cert_V2 CMS Attribute (an ASN.1 SEQUENCE containing the correct OID and ESSCertID or ESSCertIDv2), as is appropriate, depending on what digest algorithm type is provided (see RFC 5035).

Parameters:

• in_signer_cert (X509Certificate) – – the X509 public-key certificate of the signature’s signer (mathematically associated with private key to be used)

• in_digest_algorithm_type (int) – – the digest algorithm to be used

Return type:

std::vector< UChar,std::allocator< UChar > >

Returns:

the BER-serialized bytes of an ESS_signing_cert or ESS_signing_cert_V2 CMS attribute

apryse_sdk.DigitalSignatureField_SetDigSigLogFilename(filename)

Sets the digital signature logging filename, and enables the logging. This function is expected to be called only once. Subsequent calls to the function will have no effect.

Parameters:

filename (string) – The name (and path) of the log file.

Return type:

boolean

Returns:

True if this operation was successful and false if it failed because the logging process has already started.

apryse_sdk.DigitalSignatureField_SignDigest(args)

Overload 1:

Returns a CMS detached signature incorporating a digest that is provided using the provided PKCS #12 key file (.pfx). This function is part of the custom signing API, but cannot be used for workflows where the key is not in PFX format or when the signature comes from a source that cannot generate CMS signatures (e.g. Hardware Security Modules (HSM) devices, cloud signing services). In such cases, the low-level parts of the custom signing API should be used instead of this function (e.g. GenerateESSSigningCertPAdESAttribute, GenerateCMSSignedAttributes, GenerateCMSSignature). This function is a shortcut for situations in which use of more low-level custom signing functions is unnecessary. Therefore, this function will generate necessary CMS components, such as signedAttrs, internally. Notes: This function does not change the DigitalSignatureField. Call SaveCustomSignature to write a signature to its PDFDoc.

Parameters:

• in_digest (std::vector< UChar,std::allocator< UChar > >) – – the document digest value to use

• in_pkcs12_keyfile_path (string) – – the path to the PKCS #12 key file (usually has a .pfx extension) to use for signing

• in_keyfile_password (string) – – the password to use to decrypt the PKCS #12 key file

• in_pades_mode (boolean) – – whether to create a PAdES-type signature (PDF Advanced Electronic Signatures standards)

• in_digest_algorithm_type (int) – – the identifier to use to write the digest algorithm

Return type:

std::vector< UChar,std::allocator< UChar > >

Returns:

the DER-serialized bytes of a CMS detached signature (CMS ContentInfo)

Overload 2:

Returns a CMS detached signature incorporating a digest that is provided using the provided PKCS #12 key buffer (.pfx). This function is part of the custom signing API, but cannot be used for workflows where the key is not in PFX format or when the signature comes from a source that cannot generate CMS signatures (e.g. Hardware Security Modules (HSM) devices, cloud signing services). In such cases, the low-level parts of the custom signing API should be used instead of this function (e.g. GenerateESSSigningCertPAdESAttribute, GenerateCMSSignedAttributes, GenerateCMSSignature). This function is a shortcut for situations in which use of more low-level custom signing functions is unnecessary. Therefore, this function will generate necessary CMS components, such as signedAttrs, internally. Notes: This function does not change the DigitalSignatureField. Call SaveCustomSignature to write a signature to its PDFDoc.

Parameters:

• in_digest (std::vector< UChar,std::allocator< UChar > >) – – the document digest value to use

• in_pkcs12_buffer (std::vector< UChar,std::allocator< UChar > >) – – a buffer containing the PKCS #12 key (as usually stored in .pfx files) to use for signing

• in_keyfile_password (string) – – the password to use to decrypt the PKCS #12 key file data in the buffer

• in_pades_mode (boolean) – – whether to create a PAdES-type signature (PDF Advanced Electronic Signatures standards)

• in_digest_algorithm_type (int) – – the identifier to use to write the digest algorithm

Return type:

std::vector< UChar,std::allocator< UChar > >

Returns:

the DER-serialized bytes of a CMS detached signature (CMS ContentInfo)

class apryse_sdk.DisallowedChange(args)

Bases: object

The class DisallowedChange. Data pertaining to a change detected in a document during a digital signature modification permissions verification step, the change bein g both made after the signature was signed, and disallowed by t he signature’s permissions settings.

Destroy()

GetObjNum()

Returns the SDF object number of the indirect object associated with this DisallowedChange.

Return type:

int

Returns:

An unsigned 32-bit integer value.

GetType()

Returns an enumeration value representing the semantic type of this disallowed change.

Return type:

int

Returns:

An enumeration value of type: Type of DisallowedChange.

GetTypeAsString()

Returns a string value representing the semantic type of this disallowed change.

Return type:

string

Returns:

A string.

e_annotation_created_or_updated_or_deleted = 3

e_digital_signature_signed = 1

e_form_filled = 0

e_other = 4

e_page_template_instantiated = 2

e_unknown = 5

property m_impl

property thisown

The membership flag

class apryse_sdk.DocSnapshot(args)

Bases: object

The class DocSnapshot. Represents a state of the document.

Destroy()

Equals(snapshot)

Returns whether this snapshot’s document state is equivalent to another.

Parameters:

snapshot (DocSnapshot) – – the other snapshot with which to compare.

Return type:

boolean

Returns:

Whether this snapshot’s document state is equivalent to another.

GetHash()

Returns a hash that is unique to particular document states.

Return type:

int

Returns:

A hash that is unique to particular document states.

IsValid()

Returns whether this snapshot is valid.

Return type:

boolean

Returns:

Whether this snapshot is valid.

property m_impl

property thisown

The membership flag

class apryse_sdk.DocumentConversion(args)

Bases: object

The class DocumentConversion. Encapsulates the conversion of a single document from one format to another.

DocumentConversion instances are created through methods belonging to the Convert class. See Convert.WordToPDFConversion for an example.

CancelConversion()

Cancel the current conversion, forcing TryConvert or Convert to return.

Convert()

Perform the conversion. Will throw an exception on failure.

ConvertNextPage()

Perform the conversion. Will throw an exception on failure. Does nothing if the conversion is already complete. Use GetConversionStatus() to check if there is remaining content to be converted.

static CreateInternal(impl)

Destroy()

GetConversionStatus()

Get the state of the conversion process. Pair this with ConvertNextPage().

Return type:

int

Returns:

.

GetCurrentExcelSheetName()

Retrieve the name of the Excel sheet placed on the last converted page if any.

Return type:

string

Returns:

The name of the Excel sheet.

GetDoc()

Gets the PDFDoc from the conversion. Can be accessed at any time during or after conversion.

Return type:

PDFDoc

Returns:

The conversion’s PDFDoc.

GetErrorString()

If the conversion finsihed with some kind of error, this returns the value of the error description; otherwise returns an empty string.

Return type:

string

Returns:

The error description. Will be blank unless GetConversionStatus returns Failure.

GetHandleInternal()

GetNextExcelSheetCellCount()

Retrieve the number of cells in the Excel sheet that will be converted next.

Return type:

int

Returns:

The number of cells.

GetNumConvertedPages()

Returns the number of pages which have been added to the destination document. Will never decrease, and will not change after the conversion status becomes “complete”.

Return type:

int

Returns:

The number of pages that have been converted.

GetNumWarnings()

Return the number of warning strings generated during the conversion process. Warning: experimental interface; this method may be renamed or replaced with equivalent functionality in the future.

Return type:

int

Returns:

The number of stored warning strings.

GetProgress()

Returns a number from 0.0 to 1.0, representing the best estimate of conversion progress. This number is only an indicator, and should not be used to dictate program logic (in particular, it is possible for this method to return 1.0 while there is still work to be done. Use GetConversionStatus() to find out when the conversion is fully complete).

Return type:

double

Returns:

The conversion progress. Will never return a smaller number than a previous call.

GetProgressLabel()

Returns the label for the current conversion stage. May return a blank string. Warning: experimental interface; this method may be renamed or replaced with equivalent functionality in the future.

Return type:

string

Returns:

The stage label.

GetWarningString(index)

Retrieve warning strings that have been collected during the conversion process. Warning: experimental interface; this method may be renamed or replaced with equivalent functionality in the future.

Parameters:

index (int) – – the index of the string to be retrieved. Must be less than GetNumWarnings().

Return type:

string

Returns:

The value of the particular warning string.

HasProgressTracking()

Determine whether this DocumentConversion has progress reporting capability.

Return type:

boolean

Returns:

True if GetProgress is expected to return usable values.

IsCancelled()

Has the conversion been cancelled?.

Return type:

boolean

Returns:

Returns true if CancelConversion has been called previously.

SkipNextExcelSheet()

Skip the next Excel sheet. The sheet will not be converted.

TryConvert()

Perform the conversion. If the result of the conversion is failure, then GetErrorString will contain further information about the failure.

Return type:

int

Returns:

Indicates that the conversion succeeded, failed, or was cancelled.

eFailure = 2

eIncomplete = 1

eSuccess = 0

property m_impl

property thisown

The membership flag

apryse_sdk.DocumentConversion_CreateInternal(impl)

class apryse_sdk.EPUBOutputOptions

Bases: object

A class containing options common to ToEpub functions

SetExpanded(expanded)

Create the EPUB in expanded format. Default is false.

Parameters:

expanded (boolean) – if false a single EPUB file will be generated, otherwise, the generated EPUB will be in unzipped (expanded) format

SetReuseCover(reuse)

Set whether the first content page in the EPUB uses the cover image or not. If this is set to true, then the first content page will simply wrap the cover image in HTML. Otherwise, the page will be converted the same as all other pages in the EPUB. Default is false.

Parameters:

reuse (boolean) – if true the first page will simply be EPUB cover image, otherwise, the first page will be converted the same as the other pages

property thisown

The membership flag

class apryse_sdk.Element(args)

Bases: object

Element is the abstract interface used to access graphical elements used to build the display list.

Just like many other classes in PDFNet (e.g. ColorSpace, Font, Annot, etc), Element class follows the composite design pattern. This means that all Elements are accessed through the same interface, but depending on the Element type (that can be obtained using GetType()), only methods related to that type can be called. For example, if GetType() returns e_image, it is illegal to call a method specific to another Element type (i.e. a call to a text specific GetTextData() will throw an Exception).

GetBBox()

Obtains the bounding box for a graphical element.

Calculates the bounding box for a graphical element (i.e. an Element that belongs to one of following types: e_path, e_text, e_image, e_inline_image, e_shading e_form). The returned bounding box is guaranteed to encompass the Element, but is not guaranteed to be the smallest box that could contain the element. For example, for Bezier curves the bounding box will enclose all control points, not just the curve itself.

Return type:

Rect

Returns:

true if this is a graphical element and the bounding box can be calculated; false for non-graphical elements which don’t have bounding box.

Parameters:

out_bbox – (Filled by the method) A reference to a rectangle specifying the bounding box of Element (a rectangle that surrounds the entire element). The coordinates are represented in the default PDF page coordinate system and are using units called points ( 1 point = 1/72 inch = 2.54 /72 centimeter). The bounding box already accounts for the effects of current transformation matrix (CTM), text matrix, font size, and other properties in the graphics state. If this is a non-graphical element (i.e. the method returns false) the bounding box is undefined.

GetBitsPerComponent()

Return type:

int

Returns:

the number of bits used to represent each color component. Only a single value may be specified; the number of bits is the same for all color components. Valid values are 1, 2, 4, and 8.

GetCTM()

Return type:

Matrix2D

Returns:

Current Transformation Matrix (CTM) that maps coordinates to the initial user space.

GetCharIterator()

Return type:

CharIterator

Returns:

a CharIterator addressing the first CharData element in the text run.

CharIterator points to CharData. CharData is a data structure that contains the char_code number (used to retrieve glyph outlines, to map to Unicode, etc.), character positioning information (x, y), and the number of bytes taken by the character within the text buffer.

Notes: CharIterator follows the standard STL forward-iterator interface.

An example of how to use CharIterator.

for (CharIterator itr = element.GetCharIterator(); itr.HasNext(); itr.Next()) {
                unsigned int char_code = itr.Current().char_code;
                double char_pos_x = itr.Current().x;
                double char_pos_y = itr.Current().y;
}

Character positioning information (x, y) is represented in text space. In order to get the positioning in the user space, the returned value should be scaled using the text matrix (GetTextMatrix()) and the current transformation matrix (GetCTM()). See section 4.2 ‘Other Coordinate Spaces’ in PDF Reference Manual for details and PDFNet FAQ - “How do I get absolute/relative text and character positioning?”.

within a text run a character may occupy more than a single byte (e.g. in case of composite/Type0 fonts). The role of CharIterator/CharData is to provide a uniform and easy to use interface to access character information.

GetComponentNum()

Return type:

int

Returns:

the number of color components per sample.

GetDecodeArray()

Return type:

Obj

Returns:

Decode array or NULL if the parameter is not specified. A decode object is an array of numbers describing how to map image samples into the range of values appropriate for the color space of the image. If ImageMask is true, the array must be either [0 1] or [1 0]; otherwise, its length must be twice the number of color components required by ColorSpace. Default value depends on the color space, See Table 4.36 in PDF Ref. Manual.

GetGState()

Return type:

GState

Returns:

GState of this Element

GetImageColorSpace()

Convert PDF image to GDI+ Bitmap.

Return type:

ColorSpace

Returns:

GDI+ bitmap from this image. PDFNet creates a GDI+ bitmap that closely matches the original image in terms of the image depth and the number of color channels. PDF color spaces that do not have a counterpart in GDI+ are converted to RGB.

Notes: This method is available only on Windows platforms.

Return type:

ColorSpace

Returns:

The SDF object representing the color space in which image are specified or NULL if the image is an image mask

The returned color space may be any type of color space except Pattern.

GetImageData()

Return type:

Filter

Returns:

A stream (filter) containing decoded image data

GetImageDataSize()

Return type:

int

Returns:

the size of image data in bytes

GetImageHeight()

Return type:

int

Returns:

the height of the image, in samples.

GetImageRenderingIntent()

Return type:

int

Returns:

The color rendering intent to be used in rendering the image.

GetImageWidth()

Return type:

int

Returns:

the width of the image, in samples.

GetMCPropertyDict()

Return type:

Obj

Returns:

a dictionary containing the property list or NULL if property dictionary is not present.

Notes: the function automatically looks under Properties sub-dictionary of the current resource dictionary if the dictionary is not in-line. Therefore you can assume that returned Obj is dictionary if it is not NULL.

GetMCTag()

Return type:

Obj

Returns:

a tag is a name object indicating the role or significance of the marked content point/sequence.

GetMask()

Return type:

Obj

Returns:

an image XObject defining an image mask to be applied to this image (See ‘Explicit Masking’, 4.8.5), or an array specifying a range of colors to be applied to it as a color key mask (See ‘Color Key Masking’).

If IsImageMask() return true, this method will return NULL.

GetNewTextLineOffset()

Returns the offset (out_x, out_y) to the start of the current line relative to the beginning of the previous line.

out_x and out_y are numbers expressed in unscaled text space units. The returned numbers correspond to the arguments of ‘Td’ operator.

GetParentStructElement()

Return type:

SElement

Returns:

Parent logical structure element (such as ‘span’ or ‘paragraph’). If the Element is not associated with any structure element, the returned SElement will not be valid (i.e. selem.IsValid() -> false).

GetPathData()

Returns the PathData stored by the path element.

Return type:

PathData

Returns:

The PathData which contains the operators and corresponding point data.

GetPosAdjustment()

Return type:

double

Returns:

The number used to adjust text matrix in horizontal direction when drawing text. The number is expressed in thousandths of a unit of text space. The returned number corresponds to a number value within TJ array. For ‘Tj’ text strings the returned value is always 0.

Notes: because CharIterator positioning information already accounts for TJ adjustments this method is rarely used.

GetShading()

Return type:

Shading

Returns:

the SDF object of the Shading object.

GetStructMCID()

Return type:

int

Returns:

Marked Content Identifier (MCID) for this Element or a negative number if the element is not assigned an identifier/MCID.

Marked content identifier can be used to associate an Element with logical structure element that refers to the Element.

GetTextData()

Return type:

std::vector< unsigned char,std::allocator< unsigned char > >

Returns:

a pointer to the internal text buffer for this text element.

Notes: GetTextData() returns the raw text data and not a Unicode string. In PDF text can be encoded using various encoding schemes so it is necessary to consider Font encoding while processing the content of this buffer.

Most of the time GetTextString() is what you are looking for instead. GetTextString() maps the raw text directly into Unicode (as specified by Adobe Glyph List (AGL) ). Even if you would prefer to decode text yourself it is more convenient to use CharIterators returned by CharBegin()/CharEnd() and PDF::Font code mapping methods.

the buffer owner is the current element (i.e. ElementReader or ElementBuilder).

GetTextDataSize()

Return type:

int

Returns:

the size of the internal text buffer returned in GetTextData().

GetTextLength()

Return type:

double

Returns:

The text advance distance in text space.

The total sum of all of the advance values from rendering all of the characters within this element, including the advance value on the glyphs, the effect of properties such as ‘char-spacing’, ‘word-spacing’ and positioning adjustments on ‘TJ’ elements.

Notes: Computed text length is represented in text space. In order to get the length of the text run in the user space, the returned value should be scaled using the text matrix (GetTextMatrix()) and the current transformation matrix (GetCTM()). See section 4.2 ‘Other Coordinate Spaces’ in PDF Reference Manual for details.

GetTextMatrix()

Return type:

Matrix2D

Returns:

a reference to the current text matrix (Tm).

GetTextString()

Return type:

string

Returns:

a pointer to Unicode string for this text Element. The function maps character codes to Unicode array defined by Adobe Glyph List (http://partners.adobe.com/asn/developer/type/glyphlist.txt).

Notes: In PDF text can be encoded using various encoding schemes and in some cases it is not possible to extract Unicode encoding. If it is not possible to map charcode to Unicode the function will map a character to undefined code, 0xFFFD. This code is defined in private Unicode range.

If you would like to map raw text to Unicode (or some other encoding) yourself use CharIterators returned by CharBegin()/CharEnd() and PDF::Font code mapping methods.

The string owner is the current element (i.e. ElementReader or ElementBuilder).

GetType()

Return type:

int

Returns:

the current element type.

GetXObject()

Return type:

Obj

Returns:

the SDF object of the Image/Form object.

HasTextMatrix()

Return type:

boolean

Returns:

true if this element is directly associated with a text matrix (that is Tm operator is just before this text element) or false if the text matrix is default or is inherited from previous text elements.

IsClipWindingFill()

Return type:

boolean

Returns:

true if the current clip path is using non-zero winding rule, or false for even-odd rule.

IsClippingPath()

Return type:

boolean

Returns:

true if the current path element is a clipping path and should be added to clipping path stack.

IsFilled()

Return type:

boolean

Returns:

true if the current path element should be filled

IsImageInterpolate()

Return type:

boolean

Returns:

a boolean indicating whether image interpolation is to be performed.

IsImageMask()

Return type:

boolean

Returns:

a boolean indicating whether the inline image is to be treated as an image mask.

IsOCVisible()

Return type:

boolean

Returns:

true if this element is visible in the optional-content context (OCG::Context). The method considers the context’s current OCMD stack, the group ON-OFF states, the non-OC drawing status, the drawing and enumeration mode, and the intent.

When enumerating page content, OCG::Context can be passed as a parameter in ElementReader.Begin() method. When using PDFDraw, PDFRasterizer, or PDFView class to render PDF pages use PDFDraw::SetOCGContext() method to select an OC context.

IsStroked()

Return type:

boolean

Returns:

true if the current path element should be stroked

IsWindingFill()

Return type:

boolean

Returns:

true if the current path should be filled using non-zero winding rule, or false if the path should be filled using even-odd rule.

According non-zero winding rule, you can determine whether a test point is inside or outside a closed curve as follows: Draw a line from a test point to a point that is distant from the curve. Count the number of times the curve crosses the test line from left to right, and count the number of times the curve crosses the test line from right to left. If those two numbers are the same, the test point is outside the curve; otherwise, the test point is inside the curve.

According to even-odd rule, you can determine whether a test point is inside or outside a closed curve as follows: Draw a line from the test point to a point that is distant from the curve. If that line crosses the curve an odd number of times, the test point is inside the curve; otherwise, the test point is outside the curve.

SetClipWindingFill(winding_rule)

Sets clipping path’s fill rule.

Parameters:

winding_rule (boolean) – if winding_rule is true clipping should use non-zero winding rule, or false for even-odd rule.

SetNewTextLineOffset(dx, dy)

Sets the offset (dx, dy) to the start of the current line relative to the beginning of the previous line.

Parameters:

• dx (double) – horizontal offset to the start of the curret line

• dy (double) – vertical offset to the start of the current line

SetPathClip(clip)

Indicate whether the path is a clipping path or non-clipping path

Parameters:

clip (boolean) – true to set path to clipping path. False for non-clipping path.

SetPathData(data)

Set the PathData of this element. The PathData contains the array of points stored by the element and the array of path segment types.

SetPathFill(fill)

Indicate whether the path should be filled

Parameters:

fill (boolean) – true to set path to be filled. False for no fill path.

SetPathStroke(stroke)

Indicate whether the path should be stroked

Parameters:

stroke (boolean) – true to set path to be stroked. False for no stroke path.

SetPosAdjustment(adjust)

Parameters:

adjust (double) – number to set the horizontal adjustment to

Notes: Positive values move the current text element backwards (along text direction).

Negative values move the current text element forward (along text direction).

SetTextData(buf_text_data, text_data_size)

Set the text data for the current e_text Element.

Parameters:

• buf_text_data (UChar) – a pointer to a buffer containing text.

• text_data_size (int) – the size of the internal text buffer

SetTextMatrix(args)

Overload 1:

Sets the text matrix for a text element.

Parameters:

mtx (Matrix2D) – The new text matrix for this text element

Overload 2:

Sets the text matrix for a text element. This method accepts text transformation matrix components directly.

A transformation matrix in PDF is specified by six numbers, usually in the form of an array containing six elements. In its most general form, this array is denoted [a b c d h v]; it can represent any linear transformation from one coordinate system to another. For more information about PDF matrices please refer to section 4.2.2 ‘Common Transformations’ in PDF Reference Manual, and to documentation for Matrix2D class.

Parameters:

• a (double) –

  • horizontal ‘scaling’ component of the new text matrix.

• b (double) –

  • ‘rotation’ component of the new text matrix.

• c (double) –

  • ‘rotation’ component of the new text matrix.

• d (double) –

  • vertical ‘scaling’ component of the new text matrix.

• h (double) –

  • horizontal translation component of the new text matrix.

• v (double) –

  • vertical translation component of the new text matrix.

SetWindingFill(winding_rule)

Sets path’s fill rule.

Parameters:

winding_rule (boolean) – if winding_rule is true path will be filled using non-zero winding fill rule, otherwise even-odd fill will be used.

UpdateTextMetrics()

Recompute the character positioning information (i.e. CharIterator-s) and text length.

Element objects caches text length and character positioning information. If the user modifies the text data or graphics state the cached information is not correct. UpdateTextMetrics() can be used to recalculate the correct positioning and length information.

e_form = 9

e_group_begin = 10

e_group_end = 11

e_image = 6

e_inline_image = 7

e_marked_content_begin = 12

e_marked_content_end = 13

e_marked_content_point = 14

e_null = 0

e_path = 1

e_shading = 8

e_text = 3

e_text_begin = 2

e_text_end = 5

e_text_new_line = 4

property mp_elem

property thisown

The membership flag

class apryse_sdk.ElementBuilder

Bases: object

ElementBuilder is used to build new PDF::Elements (e.g. image, text, path, etc) from scratch. In conjunction with ElementWriter, ElementBuilder can be used to create new page content.

Notes: Analogous to ElementReader, every call to ElementBuilder.Create? method destroys the Element currently associated with the builder and all previous Element pointers are invalidated.

For C++ developers. Analogous to ElementReader, ElementBuilder is the owner of all Element objects it creates.

ArcTo(args)

Overload 1:

Draw an arc with the specified parameters (lower left corner, width, height and angles).

Parameters:

• x (double) – The horizontal x coordinate of the lower left corner of the ellipse encompassing rectangle

• y (double) – The horizontal y coordinate of the lower left corner of the ellipse encompassing rectangle

• width (double) – overall width of the full ellipse (not considering the angular extents).

• height (double) – overall height of the full ellipse (not considering the angular extents).

• start (double) – starting angle of the arc in degrees

• extent (double) – angular extent of the arc in degrees

Overload 2:

Draw an arc from the current point to the end point.

Parameters:

• xr (double) – x radius for the arc

• yr (double) – y radius for the arc

• rx (double) – x-axis rotation in radians

• isLargeArc (boolean) – indicates if smaller or larger arc is chosen 1 - one of the two larger arc sweeps is chosen 0 - one of the two smaller arc sweeps is chosen

• sweep (boolean) – direction in which arc is drawn (1 - clockwise, 0 - counterclockwise)

• endX (double) – x coordinate of end point

• endY (double) – y coordinate of end point

Notes: The Arc is defined the same way as it is specified by SVG or XPS standards. For

further questions please refer to the XPS or SVG standards.

ClosePath()

Closes the current subpath.

CreateEllipse(x, y, width, height)

Create an ellipse (or circle, if width == height) path Element.

Parameters:

• x (double) – The horizontal x coordinate of the ellipse center.

• y (double) – The vertical y coordinate of the ellipse center.

• width (double) – The width of the ellipse rectangle.

• height (double) – The height of the ellipse rectangle.

Return type:

Element

Returns:

the path Element

CreateForm(args)

Overload 1:

Create a Form XObject Element.

Parameters:

form (Obj) – a Form XObject content stream

Overload 2:

Create a Form XObject Element using the content of the existing page. This method assumes that the XObject will be used in the same document as the given page. If you need to create the Form XObject in a different document use CreateForm(Page, Doc) method.

Parameters:

page (Page) – A page used to create the Form XObject.

Overload 3:

Create a Form XObject Element using the content of the existing page. Unlike CreateForm(Page) method, you can use this method to create form in another document.

Parameters:

• page (Page) – A page used to create the Form XObject.

• doc (PDFDoc) – Destination document for the Form XObject.

CreateGroupBegin()

Create e_group_begin Element (i.e. ‘q’ operator in PDF content stream). The function saves the current graphics state.

CreateGroupEnd()

Create e_group_end Element (i.e. ‘Q’ operator in PDF content stream). The function restores the previous graphics state.

CreateImage(args)

Overload 1:

Create a content image Element out of a given document Image.

Parameters:

img (Image) – the given image.

Overload 2:

Create a content image Element out of a given document Image.

Parameters:

• img (Image) – the given image.

• mtx (Matrix2D) – the image transformation matrix.

Overload 3:

Create a content image Element out of a given document Image with the lower left corner at (x, y), and scale factors (hscale, vscale).

Parameters:

• img (Image) – the given image.

• x (double) – The horizontal x position to place the lower left corner of the image

• y (double) – The vertical x position to place the lower left corner of the image

• hscale (double) – The horizontal scale of the image

• vscale (double) – The vertical scale of the image

CreateMarkedContentBegin(tag, property_dict)

Create e_marked_content_begin element with an associated property dictionary (i.e. BMC or BDC operator in PDF content stream).

Parameters:

• tag (string) – the tag entry for this element.

• property_dict (Obj) – the property dictionary.

Return type:

Element

Returns:

the marked content begin element.

CreateMarkedContentBeginInlineProperties(tag)

Create e_marked_content_begin element with an inline property dictionary (i.e. BDC operator in PDF content stream).

Parameters:

tag (string) – the tag entry for this element.

Return type:

Element

Returns:

the marked content begin element.

Notes: The inline property dictionary can be accessed and edited using element.GetMCPropertyDict()

CreateMarkedContentEnd()

Create e_marked_content_end element (i.e. EMC operator in PDF content stream).

Return type:

Element

Returns:

the marked content end element.

CreateMarkedContentPoint(tag, property_dict)

Create e_marked_content_point element with an associated property dictionary (i.e. MP or DP operator in PDF content stream).

Parameters:

• tag (string) – the tag entry for this element.

• property_dict (Obj) – the property dictionary.

Return type:

Element

Returns:

the marked content point element.

CreateMarkedContentPointInlineProperties(tag)

Create e_marked_content_point element with an inline property dictionary (i.e. DP operator in PDF content stream).

Parameters:

tag (string) – the tag entry for this element.

Return type:

Element

Returns:

the marked content point element.

Notes: The inline property dictionary can be accessed and edited using element.GetMCPropertyDict()

CreatePath(points, seg_types)

Create a path Element using given path segment data

Return type:

Element

Returns:

the path Element

CreateRect(x, y, width, height)

Create a rectangle path Element.

Parameters:

• x (double) – The horizontal coordinate of the lower left corner of the rectangle.

• y (double) – The vertical coordinate of the lower left corner of the rectangle.

• width (double) – The width of the rectangle.

• height (double) – The height of the rectangle.

Return type:

Element

Returns:

the path Element

CreateShading(sh)

Parameters:

sh (Shading) – A Shading object. Shading objects represent a flat interface around all PDF shading types (e_function_shading, e_axial_shading, etc.) Create a shading Element.

CreateShapedTextRun(text_data)

Create a new text run from shaped text. Shaped Text can be created with an approriate Font, using the Font::GetShapedText() method.

Parameters:

text_data (ShapedText) – the shaped text data

Notes: you must set the current Font and font size before calling this function and the font must be created using Font::CreateCIDTrueTypeFont() method, and should be the same font used to generate the shaped text content.

For best results, the font should be encoded using the e_Indices encoding scheme.

a text run can be created only within a text block

CreateTextBegin(args)

Overload 1:

Start a text block (‘BT’ operator in PDF content stream). The function installs the given font in the current graphics state.

Parameters:

• font (Font) – font to set the text in the text block to

• font_sz (double) – size to set the text in the text block to

Overload 2:

Start a text block (‘BT’ operator in PDF content stream).

CreateTextEnd()

Ends a text block.

CreateTextNewLine(args)

Overload 1:

Create e_text_new_line Element (i.e. a Td operator in PDF content stream). Move to the start of the next line, offset from the start of the current line by (dx , dy). dx and dy are numbers expressed in unscaled text space units.

Parameters:

• dx (double) – The horizontal x offset from the start of the current line

• dy (double) – The vertical y offset from the start of the current line

Return type:

Element

Returns:

the path Element

Overload 2:

Create e_text_new_line Element (i.e. a T operator in PDF content stream).

Return type:

Element

Returns:

the path Element

CreateTextRun(args)

Overload 1:

Create a text run using the given font. Notes: a text run can be created only within a text block

Overload 2:

Create a new text run. Notes: a text run can be created only within a text block you must set the current Font and font size before calling this function.

CreateUnicodeTextRun(text_data, text_data_sz)

Create a new Unicode text run.

Parameters:

• text_data (int) – pointer to Unicode text

• text_data_sz (int) – number of characters (not bytes) in text_data

Notes: you must set the current Font and font size before calling this function and the font must be created using Font::CreateCIDTrueTypeFont() method.

a text run can be created only within a text block

CurveTo(cx1, cy1, cx2, cy2, x2, y2)

Draw a Bezier curve from the current point to the given point (x2, y2) using (cx1, cy1) and (cx2, cy2) as control points.

Parameters:

• cx1 (double) – The x component of the first control point

• cy1 (double) – The y component of the first control point

• cx2 (double) – The x component of the second control point

• cy2 (double) – The y component of the second control point

• x2 (double) – The horizontal x component of the goal point

• y2 (double) – The vertical y component of the goal point

Destroy()

Frees the native memory of the object.

Ellipse(x, y, width, height)

Add an ellipse (or circle, if rx == ry) to the current path as a complete subpath. Setting the current point is not required before using this function.

Parameters:

• x (double) – The x coordinate of the ellipse center.

• y (double) – The y coordinate of the ellipse center.

• width (double) – The x radii of the ellipse.

• height (double) – The y radii of the ellipse.

LineTo(x, y)

Draw a line from the current point to the given point.

Parameters:

• x (double) – The horizontal x component of the goal point

• y (double) – The vertical y component of the goal point

MoveTo(x, y)

Set the current point.

Parameters:

• x (double) – The horizontal x component of the point

• y (double) – The vertical y component of the point

PathBegin()

Starts building a new path Element that can contain an arbitrary sequence of lines, curves, and rectangles.

PathEnd()

Finishes building of the path Element.

Return type:

Element

Returns:

the path Element

Rect(x, y, width, height)

Add a rectangle to the current path as a complete subpath. Setting the current point is not required before using this function.

Parameters:

• x (double) – The x coordinate of the lower left corner of the rectangle.

• y (double) – The y coordinate of the lower left corner of the rectangle.

• width (double) – The width of the rectangle.

• height (double) – The height of the rectangle.

Reset(args)

The function sets the graphics state of this Element to the given value. If ‘gs’ parameter is not specified or is NULL the function resets the graphics state of this Element to the default graphics state (i.e. the graphics state at the beginning of the display list).

The function can be used in situations where the same ElementBuilder is used to create content on several pages, XObjects, etc. If the graphics state is not Reset() when moving to a new display list, the new Element will have the same graphics state as the last Element in the previous display list (and this may or may not be your intent).

Another use of Reset(gs) is to make sure that two Elements have the graphics state.

Parameters:

gs (GState) – GState (graphics state) object. If NULL or unspecified, resets graphics state to default.

property mp_builder

property thisown

The membership flag

class apryse_sdk.ElementReader(args)

Bases: object

ElementReader can be used to parse and process content streams. ElementReader provides a convenient interface used to traverse the Element display list of a page. The display list representing graphical elements (such as text-runs, paths, images, shadings, forms, etc) is accessed using the intrinsic iterator. ElementReader automatically concatenates page contents spanning multiple streams and provides a mechanism to parse contents of sub-display lists (e.g. forms XObjects and Type3 fonts).

A sample use case for ElementReader is given below:

   ...
   ElementReader reader;
   reader.Begin(page);
   for (Element element=reader.Next(); element; element = reader.Next()) // Read page contents
   {
     switch (element.GetType())    {
       case Element::e_path: { // Process path data...
          double data = element.GetPathPoints();
           int sz = element.GetPointCount();
       }
       break;
       case Element::e_text:
           // ...
       break;
     }
   }
   reader.End();

For a full sample, please refer to ElementReader and ElementReaderAdvTest sample projects.

AppendResource(res)

Parameters:

res (Obj) – resource dictionary for finding images, fonts, etc.

Begin(args)

Overload 1:

Begin processing a page.

Parameters:

• page (Page) – A page to start processing.

• ocg_context (Context) – An optional parameter used to specify the Optional Content (OC) Context that should be used when processing the page. When the OCG::Context is specified, Element::IsOCVisible() will return ‘true’ or ‘false’ depending on the visibility of the current Optional Content Group (OCG) and the states of flags in the given context.

Notes: When page processing is completed, make sure to call ElementReader.End().

Overload 2:

Begin processing given content stream. The content stream may be a Form XObject, Type3 glyph stream, pattern stream or any other content stream.

Parameters:

• content_stream (Obj) –

  • A stream object representing the content stream (usually

  a Form XObject).

• resource_dict (Obj) –

  • An optional ‘/Resource’ dictionary parameter.

  If content stream refers to named resources that are not present in the local Resource dictionary, the names are looked up in the supplied resource dictionary.

• ocg_context (Context) – An optional parameter used to specify the Optional Content (OC) Context that should be used when processing the page. When the OCG::Context is specified, Element::IsOCVisible() will return ‘true’ or ‘false’ depending on the visibility of the current Optional Content Group (OCG) and the states of flags in the given context.

Notes: When page processing is completed, make sure to call ElementReader.End().

Overload 3:

Begin processing given content stream. The content stream may be a Form XObject, Type3 glyph stream, pattern stream or any other content stream.

Parameters:

• content_stream (Obj) –

  • A stream object representing the content stream (usually

  a Form XObject).

• resource_dict (Obj) –

  • An optional ‘/Resource’ dictionary parameter.

  If content stream refers to named resources that are not present in the local Resource dictionary, the names are looked up in the supplied resource dictionary.

• ocg_context – An optional parameter used to specify the Optional Content (OC) Context that should be used when processing the page. When the OCG::Context is specified, Element::IsOCVisible() will return ‘true’ or ‘false’ depending on the visibility of the current Optional Content Group (OCG) and the states of flags in the given context.

Notes: When page processing is completed, make sure to call ElementReader.End().

Overload 4:

Begin processing given content stream. The content stream may be a Form XObject, Type3 glyph stream, pattern stream or any other content stream.

Parameters:

• content_stream (Obj) –

  • A stream object representing the content stream (usually

  a Form XObject).

• resource_dict –

  • An optional ‘/Resource’ dictionary parameter.

  If content stream refers to named resources that are not present in the local Resource dictionary, the names are looked up in the supplied resource dictionary.

• ocg_context – An optional parameter used to specify the Optional Content (OC) Context that should be used when processing the page. When the OCG::Context is specified, Element::IsOCVisible() will return ‘true’ or ‘false’ depending on the visibility of the current Optional Content Group (OCG) and the states of flags in the given context.

Notes: When page processing is completed, make sure to call ElementReader.End().

ClearChangeList()

Clear the list containing identifiers of modified graphics state attributes. The list of modified attributes is then accumulated during a subsequent call(s) to ElementReader.Next().

Current()

Return type:

Element

Returns:

the current Element or a ‘NULL’ Element. The current element is the one returned in the last call to Next().

Notes: Every call to ElementReader::Next() destroys the current Element. Therefore, an Element becomes invalid after subsequent ElementReader::Next() operation.

Destroy()

Frees the native memory of the object.

End()

Close the current display list.

If the current display list is a sub-list created using FormBegin(), PatternBegin(), or Type3FontBegin() methods, the function will end the sub-list and will return processing to the parent display list at the point where it left off before entering the sub-list.

Return type:

boolean

Returns:

true if the closed display list is a sub-list or false if it is a root display list.

FormBegin()

When the current element is a form XObject you have the option to skip form processing (by not calling FormBegin()) or to open the form stream and continue Element traversal into the form.

To open a form XObject display list use FormBegin() method. The Next() returned Element will be the first Element in the form XObject display list. Subsequent calls to Next() will traverse form’s display list until NULL is returned. At any point you can close the form sub-list using ElementReader::End() method. After the form display list is closed (using End()) the processing will return to the parent display list at the point where it left off before entering the form XObject.

GetChangesIterator()

Return type:

GSChangesIterator

Returns:

an iterator to the beginning of the list containing identifiers of modified graphics state attributes since the last call to ClearChangeList(). The list can be consulted to determine which graphics states were modified between two Elements. Attributes are ordered in the same way as they are set in the content stream. Duplicate attributes are eliminated.

GetColorSpace(name)

Parameters:

name (string) – string of the name of the SDF/Cos object to get

Notes: see ElementReader::GetFont

GetExtGState(name)

Parameters:

name (string) – string of the name of the SDF/Cos object to get

Notes: see ElementReader::GetFont

GetFont(name)

Parameters:

name (string) – string of the name of the SDF/Cos object to get

Return type:

Obj

Returns:

SDF/Cos object matching the specified name in the current resource dictionary. For ‘Page’ the name is looked up in the page’s /Resources/<Class> dictionary. For Form XObjects, Patterns, and Type3 fonts that have a content stream within page content stream the specified resource is first looked-up in the resource dictionary of the inner stream. If the resource is not found, the name is looked up in the outer content stream’s resource dictionary. The function returns NULL if the resource was not found.

GetPattern(name)

Parameters:

name (string) – string of the name of the SDF/Cos object to get

Notes: see ElementReader::GetFont

GetShading(name)

Parameters:

name (string) – string of the name of the SDF/Cos object to get

Notes: see ElementReader::GetFont

GetXObject(name)

Parameters:

name (string) – string of the name of the SDF/Cos object to get

Notes: see ElementReader::GetFont

IsChanged(attrib)

Return type:

boolean

Returns:

true if given GState attribute was changed since the last call to

Parameters:

attrib (int) – the GState attribute to test if it has been changed ClearChangeList().

Next()

Return type:

Element

Returns:

a page Element or a ‘NULL’ element if the end of current-display list was reached. You may use GetType() to determine the type of the returned Element.

Notes: Every call to ElementReader::Next() destroys the current Element. Therefore, an Element becomes invalid after subsequent ElementReader::Next() operation.

PatternBegin(fill_pattern, reset_ctm_tfm=False)

A method used to spawn the sub-display list representing the tiling pattern of the current element in the ElementReader. You can call this method at any point as long as the current element is valid.

Parameters:

• fill_pattern (boolean) – If true, the filling pattern of the current element will be spawned; otherwise, the stroking pattern of the current element will be spawned. Note that the graphics state will be inherited from the parent content stream (the content stream in which the pattern is defined as a resource) automatically.

• reset_ctm_tfm (boolean) – An optional parameter used to indicate whether the pattern’s display list should set its initial CTM and transformation matrices to identity matrix. In general, we should leave it to be false.

To open a tiling pattern sub-display list use PatternBegin(pattern) method. The Next() returned Element will be the first Element in the pattern display list. Subsequent calls to Next() will traverse pattern’s display list until NULL is encountered. At any point you can close the pattern sub-list using ElementReader::End() method. After the pattern display list is closed, the processing will return to the parent display list at the point where pattern display list was spawned.

Type3FontBegin(char_data, resource_dict=0)

A method used to spawn a sub-display list representing a Type3 Font glyph. You can call this method at any point as long as the current element in the ElementReader is a text element whose font type is type 3.

Parameters:

• char_data (CharData) – The information about the glyph to process. You can get this information by dereferencing a CharIterator.

• resource_dict (Obj) –

  • An optional ‘/Resource’ dictionary parameter.

  If any glyph descriptions refer to named resources but Font Resource dictionary is absent, the names are looked up in the supplied resource dictionary.

To open a Type3 font sub-display list use Type3FontBegin() method. The Next() returned Element will be the first Element in the glyph’s display list. Subsequent calls to Next() will traverse glyph’s display list until NULL is returned. At any point you can close the glyph sub-list using ElementReader::End() method. After the glyph display list is closed, the processing will return to the parent display list at the point where glyph display list was spawned.

property mp_reader

property thisown

The membership flag

class apryse_sdk.ElementWriter(args)

Bases: object

ElementWriter can be used to assemble and write new content to a page, Form XObject, Type3 Glyph stream, pattern stream, or any other content stream.

Begin(args)

Overload 1:

Begin writing to the given page.

By default, new content will be appended to the page, as foreground graphics. It is possible to add new page content as background graphics by setting the second parameter in begin method to ‘true’ (e.g. writer.Begin(page, true)).

Parameters:

• page (Page) – The page to write content.

• placement (int) – An optional flag indicating whether the new content should be added as a foreground or background layer to the existing page. By default, the new content will appear on top of the existing graphics.

• page_coord_sys (boolean) – An optional flag used to select the target coordinate system if true (default), the coordinates are relative to the lower-left corner of the page, otherwise the coordinates are defined in PDF user coordinate system (which may, or may not coincide with the page coordinates).

• compress (boolean) – An optional flag indicating whether the page content stream should be compressed. This may be useful for debugging content streams. Also some applications need to do a clear text search on strings in the PDF files. By default, all content streams are compressed.

• resources (Obj) – the resource dictionary in which to store resources for the final page. By default, a new resource dictionary will be created.

Overload 2:

Begin writing an Element sequence to a new stream. Use this function to write Elements to a content stream other than the page. For example, you can create Form XObjects (See Section ‘4.9 Form XObjects’ in PDF Reference for more details) pattern streams, Type3 font glyph streams, etc.

Parameters:

• doc (SDFDoc) –

  • A low-level SDF/Cos document that will contain the new stream. You can

  access low-level document using PDFDoc::GetSDFDoc() or Obj::GetDoc() methods.

• compress (boolean) – An optional flag indicating whether the page content stream should be compressed. This may be useful for debugging content streams. Also some applications need to do a clear text search on strings in the PDF files. By default, all content streams are compressed.

Notes: the newly created content stream object is returned when writing operations are completed (i.e. after the call to ElementWriter::End()).

Overload 3:

Begin writing an Element sequence to a new stream. Use this function to write Elements to a content stream other than the page. For example, you can create Form XObjects (See Section ‘4.9 Form XObjects’ in PDF Reference for more details) pattern streams, Type3 font glyph streams, etc.

Parameters:

• doc (SDFDoc) –

  • A low-level SDF/Cos document that will contain the new stream. You can

  access low-level document using PDFDoc::GetSDFDoc() or Obj::GetDoc() methods.

• compress – An optional flag indicating whether the page content stream should be compressed. This may be useful for debugging content streams. Also some applications need to do a clear text search on strings in the PDF files. By default, all content streams are compressed.

Notes: the newly created content stream object is returned when writing operations are completed (i.e. after the call to ElementWriter::End()).

Overload 4:

Begin writing an Element sequence to a stream. Use this function to write Elements to a content stream which will replace an existing content stream in an object passed as a parameter.

Parameters:

• stream_obj_to_update (Obj) –

  • A low-level SDF stream object that will contain the new stream.

  Old stream inside that object will be discarded.

• compress (boolean) – An optional flag indicating whether the content stream should be compressed. This may be useful for debugging content streams. Also some applications need to do a clear text search on strings in the PDF files. By default, all content streams are compressed.

• resources (Obj) – the resource dictionary in which to store resources for the final page. By default, a new resource dictionary will be created.

Notes: The content stream object is returned when writing operations are completed (i.e. after the call to ElementWriter::End()).

Overload 5:

Begin writing an Element sequence to a stream. Use this function to write Elements to a content stream which will replace an existing content stream in an object passed as a parameter.

Parameters:

• stream_obj_to_update (Obj) –

  • A low-level SDF stream object that will contain the new stream.

  Old stream inside that object will be discarded.

• compress (boolean) – An optional flag indicating whether the content stream should be compressed. This may be useful for debugging content streams. Also some applications need to do a clear text search on strings in the PDF files. By default, all content streams are compressed.

• resources – the resource dictionary in which to store resources for the final page. By default, a new resource dictionary will be created.

Notes: The content stream object is returned when writing operations are completed (i.e. after the call to ElementWriter::End()).

Overload 6:

Begin writing an Element sequence to a stream. Use this function to write Elements to a content stream which will replace an existing content stream in an object passed as a parameter.

Parameters:

• stream_obj_to_update (Obj) –

  • A low-level SDF stream object that will contain the new stream.

  Old stream inside that object will be discarded.

• compress – An optional flag indicating whether the content stream should be compressed. This may be useful for debugging content streams. Also some applications need to do a clear text search on strings in the PDF files. By default, all content streams are compressed.

• resources – the resource dictionary in which to store resources for the final page. By default, a new resource dictionary will be created.

Notes: The content stream object is returned when writing operations are completed (i.e. after the call to ElementWriter::End()).

Destroy()

Frees the native memory of the object.

End()

Finish writing to a page

Return type:

Obj

Returns:

A low-level stream object that was used to store Elements.

Flush()

The Flush method flushes all pending Element writing operations. This method is typically only required to be called when intermixing direct content writing (i.e. WriteBuffer/WriteString) with Element writing.

SetDefaultGState(reader)

This method is used to initialize ElementWriter state with the state of a given ElementReader. This can be used to avoid incorrectly writing inherited GState attributes.

Parameters:

reader (ElementReader) – ElementReader.

WriteBuffer(data)

Writes an arbitrary buffer to the content stream. This function can be used to insert comments, inline-image data, and chunks of arbitrary content to the output stream.

WriteElement(element)

Writes the Element to the content stream.

Parameters:

element (Element) – The element to write to the content stream.

WriteGStateChanges(element)

Write only the graphics state changes applied to this element and skip writing the element itself. This is especially useful when rewriting page content, but with the intention to skip certain elements.

Parameters:

element (Element) – The element for which to write graphics state changes.

WritePlacedElement(element)

A utility function that surrounds the given Element with a graphics state Save/Restore Element (i.e. in PDF content stream represented as ‘q element Q’).

The function is equivalent to calling WriteElement three times:

WriteElement(eSave); WriteElement(element); WriteElement(eRestore);

where eSave is ‘e_group_begin’ and eRestore is ‘e_group_end’ Element

The function is useful when XObjects such as Images and Forms are drawn on the page.

Parameters:

element (Element) – Element object to enact function on.

WriteString(str)

Writes an arbitrary string to the content stream. Serves the same purpose as WriteBuffer().

Parameters:

str (string) – String to write to the content stream.

e_overlay = 1

element appears on top of the existing graphics

e_replacement = 2

element will replace current page contents

e_underlay = 0

element is put in the background layer of the page

property mp_writer

property thisown

The membership flag

class apryse_sdk.EmbeddedTimestampVerificationResult(args)

Bases: object

This class represents the result of verifying a secure embedded timestamp digital signature.

Destroy()

GetCMSDigestStatus()

Retrieves the result condition associated with the CMS signed digest verification step.

Return type:

int

Returns:

A DigestStatus-type enumeration value.

GetCMSDigestStatusAsString()

Retrieves the result condition associated with the CMS signed digest verification step, as a descriptive string.

Return type:

string

Returns:

a string

Notes: Output may change in future versions.

GetCMSSignatureDigestAlgorithm()

Retrieves an enumeration value representing the digest algorithm used to sign the timestamp token.

Return type:

int

Returns:

A DigestAlgorithm enumeration value.

GetMessageImprintDigestAlgorithm()

Retrieves an enumeration value representing the digest algorithm used inside the message imprint field of the timestamp to digest the main signature value.

Return type:

int

Returns:

A DigestAlgorithm enumeration value.

GetMessageImprintDigestStatus()

Retrieves the result condition associated with the message imprint digest verification step.

Return type:

int

Returns:

A DigestStatus-type enumeration value.

GetMessageImprintDigestStatusAsString()

Retrieves the result condition associated with the message imprint digest verification step, as a descriptive string.

Return type:

string

Returns:

a string

Notes: Output may change in future versions.

GetTrustStatus()

Retrieves the result condition associated with the trust verification step.

Return type:

int

Returns:

A TrustStatus-type enumeration value.

GetTrustStatusAsString()

Retrieves the result condition associated with the trust verification step, as a descriptive string.

Return type:

string

Returns:

a string

Notes: Output may change in future versions.

GetTrustVerificationResult()

Retrieves the detailed result associated with the trust step of the verification operation that returned this EmbeddedTimestampVerificationResult, if such a detailed trust result is available. Must call HasTrustVerificationResult first and check for a true result. Notes: This function will throw if there is no trust result available.

Return type:

TrustVerificationResult

Returns:

A TrustVerificationResult object.

GetUnsupportedFeatures()

Retrieves reports about unsupported features encountered during verification of the timestamp. Current possible values:

“GeneralizedTime format with length <number greater than 15>”, “unsupported digest algorithm”

Return type:

std::vector< std::string,std::allocator< std::string > >

Returns:

a container of strings representing unsupported features encountered during verification of the timestamp

Notes: Output may change in future versions.

GetVerificationStatus()

Retrieves the main verification status. The main status is determined based on the other statuses.

Return type:

boolean

Returns:

A boolean representing whether or not the verification operation was completely successful.

HasTrustVerificationResult()

Returns whether there is a detailed TrustVerificationResult in this EmbeddedTimestampVerificationResult.

Return type:

boolean

Returns:

A boolean

property m_impl

property thisown

The membership flag

class apryse_sdk.ExcelOutputOptions

Bases: object

A class containing options common to ToExcel functions

SetCustomOCRLanguage(ocrlang)

Specifies the custom OCR languages to use. Notes: Use 3-letter ISO 639-2 language codes, separated by spaces. Example: “eng deu spa fra”. The default is English.

Parameters:

ocrlang (string) – the OCR language(s).

SetLanguage(language)

Specifies the OCR language. Default is automatic language detection.

Parameters:

language (int) – the OCR language.

SetNonTableContent(non_tables)

Specifies whether to convert non-tabular content. Default is false.

Parameters:

non_tables (boolean) – If false, only tabular content is converted to Excel. If true, all textual content is converted to Excel.

SetPDFPassword(password)

Specifies the password if the PDF requires one.

Parameters:

password (string) – the PDF password, if required; an empty string otherwise.

SetPages(page_from, page_to)

Specifies a range of pages to be converted. By default all pages are converted. The first page has the page number of 1.

Parameters:

• page_from (int) – the first page to be converted.

• page_to (int) – the last page to be converted (inclusive). Use a negative value to specify the last page in the PDF.

SetPreferredOCREngine(engine)

Specifies preferred OCR engine.

Parameters:

engine (int) – The PreferredOCREngine to OCR.

SetSingleSheet(single_sheet)

Specifies whether to combine all tables into a single sheet. Default is false.

Parameters:

single_sheet (boolean) – If false, each logical table goes to a separate Excel sheet. If true, all logical tables are combined into a single Excel sheet.

property thisown

The membership flag

class apryse_sdk.FDFDoc(args)

Bases: object

FDFDoc is a class representing Forms Data Format (FDF) documents. FDF is typically used when submitting form data to a server, receiving the response, and incorporating it into the interactive form. It can also be used to export form data to stand-alone files that can be stored, transmitted electronically, and imported back into the corresponding PDF interactive form. In addition, beginning in PDF 1.3, FDF can be used to define a container for annotations that are separate from the PDF document to which they apply.

Note: While theructor does not, a few methods in FDFDoc will cause it to count as a document for the consumption-based licensing if was not created through PDFDoc::FDFExtract(). Please consult individual API documentation for exact details.

Close()

Close FDFDoc

static CreateFromXFDF(file_name)

Create a new FDFDoc from XFDF input. Input can be either a XFDF file path, or the XFDF data itself.

Parameters:

file_name (string) –

• string containing either the file path to a XFDF file, or the XML buffer containing the XFDF.

Return type:

FDFDoc

Returns:

A new FDFDoc.

FieldCreate(args)

GetFDF()

Return type:

Obj

Returns:

the FDF dictionary located in “/Root” or NULL if dictionary is not present.

GetField(field_name)

Parameters:

field_name (string) –

• a string representing the fully qualified name of

the field (e.g. “employee.name.first”).

Return type:

FDFField

Returns:

a FDFField associated with the given field_name or invalid field (null) if the field is not found.

GetFieldIterator(args)

Overload 1:

An interactive form (sometimes referred to as an AcroForm) is a collection of fields for gathering information interactively from the user. A FDF document may contain any number of fields appearing on any combination of pages, all of which make up a single, global interactive form spanning the entire document.

The following methods are used to access and manipulate Interactive form fields (sometimes referred to as AcroForms).

Return type:

FDFFieldIterator

Returns:

an iterator to the first FDFField in the document.

Notes: if the document has no AcroForms, HasNext() will return false.

Overload 2:

An interactive form (sometimes referred to as an AcroForm) is a collection of fields for gathering information interactively from the user. A FDF document may contain any number of fields appearing on any combination of pages, all of which make up a single, global interactive form spanning the entire document.

The following methods are used to access and manipulate Interactive form fields (sometimes referred to as AcroForms).

Parameters:

field_name (string) – String representing the name of the FDFField to get.

Return type:

FDFFieldIterator

Returns:

an iterator to the FDFField in the document.

Notes: if the document has no AcroForms, HasNext() will return false.

GetID()

Get the ID entry from “/Root/FDF” dictionary.

Return type:

Obj

Returns:

• An object representing the ID entry in “/Root/FDF” dictionary.

GetPDFFileName()

Get the PDF document file that this FDF file was exported from or is intended to be imported into.

Return type:

string

Returns:

a String with the PDF document file name.

GetRoot()

Return type:

Obj

Returns:

• A dictionary representing the Cos root of the document (/Root entry

within the trailer dictionary)

Notes: This method will count as a document usage for consumption-based licensing if the current document has not yet been counted.

GetSDFDoc()

Return type:

SDFDoc

Returns:

document’s SDF/Cos document

Notes: This method will count as a document usage for consumption-based licensing if the current document has not yet been counted.

GetTrailer()

Return type:

Obj

Returns:

• A dictionary representing the Cos root of the document (document’s trailer)

Notes: This method will count as a document usage for consumption-based licensing if the current document has not yet been counted.

IsModified()

Return type:

boolean

Returns:

• true if document was modified, false otherwise

MergeAnnots(args)

Merge the annotations from XFDF file into FDF file

Parameters:

• command_file (string) –

  • string containing the xml command file path or xml string of the command

• permitted_user (string) –

  • optional user name of the permitted user

Save(args)

Overload 1:

Saves the document to a file.

If a full save is requested to the original path, the file is saved to a file system-determined temporary file, the old file is deleted, and the temporary file is renamed to path.

A full save with remove unused or linearization option may re-arrange object in the cross reference table. Therefore all pointers and references to document objects and resources should be re acquired in order to continue document editing.

In order to use incremental save the specified path must match original path and e_incremental flag bit should be set.

Parameters:

path (string) –

• The full path name to which the file is saved.

Raises:

• if the file can’t be opened for saving or if there is a problem during Save

an Exception object will be thrown.

Notes: This method will count as a document usage for consumption-based licensing if the current document has not yet been counted.

Overload 2:

Saves the document to a memory buffer.

Raises:

• if there is a problem during Save an Exception object will be thrown.

Notes: This method will count as a document usage for consumption-based licensing if the current document has not yet been counted.

SaveAsXFDF(args)

Overload 1:

Export FDF file as an XFDF file

Parameters:

filepath (string) –

• the filepath of the exported XFDF file

Overload 2:

Export FDF file as an XFDF file

Parameters:

• filepath (string) –

  • the filepath of the exported XFDF file

• opts (FDF::XFDFExportOptions) – Options controlling finer parameters of xfdf export

Overload 3:

Export FDF file as a XFDF string :param opts: Options controlling finer parameters of xfdf export

Overload 4:

Export FDF file as a XFDF string

Parameters:

opts (FDF::XFDFExportOptions) – Options controlling finer parameters of xfdf export

Return type:

string

Returns:

A UString containing the XFDF representation of the FDF file

SetID(id)

Set the ID entry in “/Root/FDF” dictionary.

Parameters:

id (Obj) –

• ID array object.

SetPDFFileName(filepath)

Set the PDF document file that this FDF file was exported from or is intended to be imported into.

Parameters:

filepath (string) –

• pathname to the file.

property mp_doc

property thisown

The membership flag

apryse_sdk.FDFDoc_CreateFromXFDF(file_name)

Create a new FDFDoc from XFDF input. Input can be either a XFDF file path, or the XFDF data itself.

Parameters:

file_name (string) –

• string containing either the file path to a XFDF file, or the XML buffer containing the XFDF.

Return type:

FDFDoc

Returns:

A new FDFDoc.

class apryse_sdk.FDFField(args)

Bases: object

FindAttribute(attrib)

The function returns the specified attribute.

Parameters:

attrib (string) –

• name of the attribute to find

Return type:

Obj

Returns:

return the attribute value if the given attribute name was found or a NULL object if the given attribute name was not found.

GetName()

Return type:

string

Returns:

a string representing the fully qualified name of the field (e.g. “employee.name.first”).

GetPartialName()

Return type:

string

Returns:

a string representing the partial name of the field (e.g. “first” when “employee.name.first” is fully qualified name).

GetSDFObj()

Return type:

Obj

Returns:

the object to the underlying SDF/Cos object.

GetValue()

Return type:

Obj

Returns:

the value of the Field (the value of its /V key) or NULL if the value is not specified. The format of field’s value varies depending on the field type.

SetValue(value)

Sets the value of the FDFField (the value of the field’s /V key).

Parameters:

value (Obj) –

• the value to set the FDFField to

Notes: in order to remove/erase the existing value use SetValue(SDF::Null)

property thisown

The membership flag

class apryse_sdk.FDFFieldIterator(args)

Bases: object

Supports a simple iteration over a generic collection.

Current()

Note: HasNext() must be true before calling Current()

Return type:

FDFField

Returns:

the current element in the collection

Destroy()

Frees the native memory of the object.

HasNext()

Return type:

boolean

Returns:

true if the iterator can be successfully advanced to the next element; false if the iterator is no longer valid.

Next()

Note: HasNext() must be true before calling Next() Advances the iterator to the next element of the collection.

property mp_impl

property thisown

The membership flag

class apryse_sdk.Field(args)

Bases: object

An interactive form (sometimes referred to as an AcroForm) is a collection of fields for gathering information interactively from the user. A PDF document may contain any number of Fields appearing on any combination of pages, all of which make up a single, global interactive form spanning the entire document.

PDFNet fully supports reading, writing, and editing PDF forms and provides many utility methods so that work with forms is simple and efficient. Using PDFNet forms API arbitrary subsets of form fields can be imported or exported from the document, new forms can be created from scratch, and the appearance of existing forms can be modified.

In PDFNet Fields are accessed through FieldIterator-s. The list of all Fields present in the document can be traversed as follows:

FieldIterator itr = pdfdoc.GetFieldIterator();
for(; itr.HasNext(); itr.Next()) {
  Field field = itr.Current();
  Console.WriteLine("Field name: {0}", field.GetName());
 }

For a full sample, please refer to ‘InteractiveForms’ sample project.

To search field by name use FieldFind method. For example:

FieldIterator itr = pdfdoc.FieldFind("name");
if (itr.HasNext()) {
  Console.WriteLine("Field name: {0}", itr.Current().GetName());
}
else { ...field was not found... }

If a given field name was not found or if the end of the field list was reached the iterator HasNext() will return false.

If you have a valid iterator you can access the Field using Current() method. For example: Field field = itr.Current();

Using Flatten(…) method it is possible to merge field appearances with the page content. Form ‘flattening’ refers to the operation that changes active form fields into a static area that is part of the PDF document, just like the other text and images in the document. A completely flattened PDF form does not have any widget annotations or interactive fields.

Destroy()

Frees the native memory of the object.

EraseAppearance()

Removes any appearances associated with the field.

FindInheritedAttribute(attrib)

Some of the Field attributes are designated as inheritable. If such an attribute is omitted from a Field object, its value is inherited from an ancestor node in the Field tree. If the attribute is a required one, a value must be supplied in an ancestor node; if it is optional and no inherited value is specified, the default value should be used.

The function walks up the Field inheritance tree in search for specified attribute.

Return type:

Obj

Returns:

The attribute value if the given attribute name was found

or a NULL object if the given attribute name was not found.

Resources dictionary (Required; inheritable) MediaBox rectangle (Required; inheritable) CropBox rectangle (Optional; inheritable) Rotate integer (Optional; inheritable)

Flatten(page)

Flatten/Merge existing form field appearances with the page content and remove widget annotation.

Form ‘flattening’ refers to the operation that changes active form fields into a static area that is part of the PDF document, just like the other text and images in the document. A completely flattened PDF form does not have any widget annotations or interactive fields.

Parameters:

page (Page) – page object to flatten

Notes: an alternative approach to set the field as read only is using Field.SetFlag(Field::e_read_only, true) method. Unlike Field.SetFlag(…), the result of Flatten() operation can not be programatically reversed.

GetDefaultAppearance()

Return type:

GState

Returns:

The default graphics state that should be used in formatting the text. The state corresponds to /DA entry in the field dictionary.

GetDefaultValue()

Return type:

Obj

Returns:

The default value to which the field reverts when a reset-form action is executed or NULL if the default value is not specified.

The format of field’s value varies depending on the field type.

GetDefaultValueAsString()

GetFlag(flag)

Return type:

boolean

Returns:

the value of given field flag

GetJustification()

Return type:

int

Returns:

the form of quadding (justification) to be used in displaying the text fields.

GetMaxLen()

Return type:

int

Returns:

The maximum length of the field’s text, in characters, or a negative number if the length is not limited.

Notes: This method is specific to a text field.

GetName()

Return type:

string

Returns:

a string representing the fully qualified name of the field (e.g. “employee.name.first”).

GetOpt(index)

Parameters:

index (int) – index position of the option to retrieve.

Return type:

string

Returns:

The string of the option at the givent index.

Notes: The index must be less than the value returned by GetOptCount().

GetOptCount()

Returns the total number of options in a list or combo box.

GetPartialName()

Return type:

string

Returns:

a string representing the partial name of the field (e.g. “first” when “employee.name.first” is fully qualified name).

GetSDFObj()

Return type:

Obj

Returns:

the underlying SDF/Cos object.

GetTriggerAction(trigger)

Get the Action associated with the selected Field Trigger event.

Parameters:

trigger (int) – the type of trigger event to get

Return type:

Obj

Returns:

the Action Obj if present, otherwise NULL

GetType()

Return type:

int

Returns:

The field’s value, whose type/format varies depending on the field type. See the descriptions of individual field types for further information.

GetUpdateRect()

Return type:

Rect

Returns:

The rectangle that should be refreshed after changing a field.

GetValue()

Return type:

Obj

Returns:

the value of the Field (the value of its /V key) or NULL if the value is not specified.

The format of field’s value varies depending on the field type.

GetValueAsBool()

Return type:

boolean

Returns:

Field value as a boolean.

Notes: This method is usually for check-box and radio button fields.

GetValueAsString()

IsAnnot()

Return type:

boolean

Returns:

true if this Field is a Widget Annotation

Determines whether or not this Field is an Annotation.

IsLockedByDigitalSignature()

Returns whether modifying this field would invalidate a digital signature in the document.

Return type:

boolean

Returns:

whether modifying this field would invalidate a digital signature in the document

IsValid()

Return type:

boolean

Returns:

whether this is a valid (non-null) Field. If the function returns false the underlying SDF/Cos object is null and the Field object should be treated as null as well.

RefreshAppearance()

Regenerates the appearance stream for the Widget Annotation containing variable text. Call this method if you modified field’s value and would like to update field’s appearance.

Notes: If this field contains text, and has been added to a rotated page, the text in the field may be rotated. If RefreshAppearance is called after the field is added to a rotated page, then any text will be rotated in the opposite direction of the page rotation. If this method is called before the field is added to any rotated page, then no counter rotation will be applied. If you wish to call RefreshAppearance on a field already added to a rotated page, but you don’t want the text to be rotated, you can do one of the following; temporarily un-rotate the page, or, temporarily remove the “P” object from the field.

Rename(field_name)

Modifies the field name.

Parameters:

field_name (string) – a string representing the fully qualified name of the field (e.g. “employee.name.first”).

SetFlag(flag, value)

Set the value of given FieldFlag.

Notes: You can use this method to set the field as read-only. An alternative approach to set the field as read only is using Page.Flatten(…) method. Unlike Flatten(…), the result of SetFlag(…) can be programatically reversed.

SetJustification(j)

Sets the justification to be used in displaying the text field.

Parameters:

j (int) – enum representing justification to set the text field to, options are e_left_justified, e_centered and e_right_justified

Notes: This method is specific to a text field.

SetMaxLen(max_len)

Sets the maximum length of the field’s text, in characters.

Parameters:

max_len (int) – maximum length of a field’s text.

Notes: This method is specific to a text field.

SetValue(args)

Overload 1:

Sets the value of the field (i.e. the value of the field’s /V key). The format of field’s value varies depending on the field type.

Parameters:

value (string) – the new field value.

Notes: in order to remove/erase the existing value use pass a SDF::Null object to SetValue().

In PDF, Field’s value is separate from its annotation (i.e. how the field appears on the page). After you modify Field’s value you need to refresh Field’s appearance using RefreshAppearance() method.

Alternatively, you can delete “AP” entry from the Widget annotation and set “NeedAppearances” flag in AcroForm dictionary (i.e. doc.GetAcroForm().Put(“NeedAppearances”, Obj.CreateBool(true)); ) This will force viewer application to auto-generate new field appearances every time the document is opened.

Yet another option is to generate a custom annotation appearance using ElementBuilder and ElementWriter and then set the “AP” entry in the widget dictionary to the new appearance stream. This functionality is useful in applications that need advanced control over how the form fields are rendered.

Overload 2:

Sets the value of a check-box or radio-button field.

Parameters:

value (boolean) – If true, the filed will be set to ‘True’, if false the field will be set to ‘False’.

Notes: This method is usually for check-box and radio button fields.

UseSignatureHandler(signature_handler_id)

Sets the signature handler to use for adding a signature to this field. If the signature handler is not found in PDFDoc’s signature handlers list, this field will not be signed. To add signature handlers, use PDFDoc.AddSignatureHandler method.

If a signature handler is already assigned to this field and this method is called once again, the associate signature handler for this field will be updated with the new handler.

Parameters:

signature_handler_id (int) – The unique id of the SignatureHandler to use for adding signature in this field.

Return type:

Obj

Returns:

The signature dictionary created using the SignatureHandler, or NULL pointer if the signature handler is not found.

e_action_trigger_calculate = 16

e_action_trigger_format = 14

e_action_trigger_keystroke = 13

e_action_trigger_validate = 15

e_button = 0

e_centered = 1

e_check = 1

e_choice = 4

e_comb = 12

e_combo = 14

e_commit_on_sel_change = 18

e_edit = 15

e_file_select = 9

e_left_justified = 0

e_multiline = 7

e_multiselect = 17

e_no_export = 2

e_no_scroll = 11

e_no_spellcheck = 10

e_null = 6

e_password = 8

e_pushbutton_flag = 3

e_radio = 2

e_radio_flag = 4

e_radios_in_unison = 6

e_read_only = 0

e_required = 1

e_rich_text = 13

e_right_justified = 2

e_signature = 5

e_sort = 16

e_text = 3

e_toggle_to_off = 5

property mp_field

property thisown

The membership flag

class apryse_sdk.FieldIterator(args)

Bases: object

Supports a simple iteration over a generic collection.

Current()

Note: HasNext() must be true before calling Current()

Return type:

Field

Returns:

the current element in the collection

Destroy()

Frees the native memory of the object.

HasNext()

Return type:

boolean

Returns:

true if the iterator can be successfully advanced to the next element; false if the iterator is no longer valid.

Next()

Note: HasNext() must be true before calling Next() Advances the iterator to the next element of the collection.

property mp_impl

property thisown

The membership flag

class apryse_sdk.FileAttachment(args)

Bases: Markup

A file attachment annotation contains a reference to a file, which may be embedded in the PDF document.

static Create(args)

Overload 1:

Creates a file attachment annotation.

A file attachment annotation contains a reference to a file, which typically is embedded in the PDF file.

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds, in user space coordinates. Note that FileAttachment icons can differ in their appearance dimensions, so you may want to match these Rectangle dimensions or the aspect ratio to avoid a squished or stretched appearance: e_Graph: 40 x 40 e_PushPin: 28 x 40 e_Paperclip: 14 x 34 e_Tag: 40 x 32

• fs (FileSpec) – a file specification object used to initialize the file attachment annotation.

• icon_name (int) – The name of an icon to be used in displaying the annotation, default is PushPin.

Notes: PDF Viewer applications should provide predefined icon appearances for at least the following standard names: Graph, PushPin, Paperclip, Tag. Additional names may be supported as well. Default value: PushPin.

Return type:

FileAttachment

Returns:

A new file attachment annotation.

Overload 2:

Creates a file attachment annotation.

A file attachment annotation contains a reference to a file, which typically is embedded in the PDF file.

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds, in user space coordinates. Note that FileAttachment icons can differ in their appearance dimensions, so you may want to match these Rectangle dimensions or the aspect ratio to avoid a squished or stretched appearance: e_Graph: 40 x 40 e_PushPin: 28 x 40 e_Paperclip: 14 x 34 e_Tag: 40 x 32

• path (string) – The path to the file which should be attached

• icon_name (int) – An icon to be used in displaying the annotation, default is PushPin.

Notes: PDF Viewer applications should provide predefined icon appearances for at least the following standard names: Graph PushPin Paperclip Tag. Additional names may be supported as well. Default value: PushPin.

Return type:

FileAttachment

Returns:

A new file attachment annotation.

Overload 3:

Creates a file attachment annotation.

A file attachment annotation contains a reference to a file, which typically is embedded in the PDF file.

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds, in user space coordinates. Note that FileAttachment icons can differ in their appearance dimensions, so you may want to match these Rectangle dimensions or the aspect ratio to avoid a squished or stretched appearance: e_Graph: 40 x 40 e_PushPin: 28 x 40 e_Paperclip: 14 x 34 e_Tag: 40 x 32

• path (string) – The path to the file which should be attached

• icon_name – An icon to be used in displaying the annotation, default is PushPin.

Notes: PDF Viewer applications should provide predefined icon appearances for at least the following standard names: Graph PushPin Paperclip Tag. Additional names may be supported as well. Default value: PushPin.

Return type:

FileAttachment

Returns:

A new file attachment annotation.

Overload 4:

Creates a file attachment annotation. This method should be used when a nonstandard icon type is desired in the annotation.

A file attachment annotation contains a reference to a file, which typically is embedded in the PDF file.

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds, in user space coordinates.

• path (string) – The path to the file which should be attached

• icon_name (string) – The name of an icon to be used in displaying the annotation.

Notes: PDF Viewer applications should provide predefined icon appearances for at least the following standard names: Graph PushPin Paperclip Tag. Additional names may be supported as well. Default value: PushPin.

Return type:

FileAttachment

Returns:

A new file attachment annotation.

static CreateAnnot(args)

Export(args)

The function saves the data referenced by this File Attachment to an external file.

If the file is embedded, the function saves the embedded file. If the file is not embedded, the function will copy the external file. If the file is not embedded and the external file can’t be found, the function returns false.

Parameters:

save_as (string) – An optional parameter indicating the filepath and filename where the data should be saved. If this parameter is not specified the function will attempt to save the file using FileSpec.GetFilePath().

Return type:

boolean

Returns:

true is the file was saved successfully, false otherwise.

GetFileSpec()

Return type:

FileSpec

Returns:

the file specification that contains a file reference or the embedded file data stream.

GetIcon()

Return type:

int

Returns:

the type the associated icon style. e_PushPin

Notes: The annotation dictionary’s appearance stream, if present, will take precedence over this entry when displaying the annotation in the viewer.

GetIconName()

Returns the name of the icon associated with the FileAttachment annotation.

Return type:

string

Returns:

A string denoting the name of the icon.

See also: GetIcon() GetIconName() returns the icon name as it appears in the annotation dictionary, while GetIcon() returns the same icon name converted to enumeration value. Notes: The annotation dictionary’s appearance stream, if present, will take precedence over this entry when displaying the annotation in the viewer.

SetFileSpec(file)

Sets the file specification.

Parameters:

file (FileSpec) – The file specification to associate with this annotation.. The file specification contains a file reference or the embedded file data stream.

SetIcon(args)

Sets the icon style associated with FileAttachment annotation. (Optional)

Parameters:

type (int) – icon style. e_PushPin

Notes: The annotation dictionary’s appearance stream, if present, will take precedence over this entry when displaying the annotation in the viewer.

SetIconName(iname)

Sets the name of the icon associated with the FileAttachment annotation. (Optional)

Parameters:

iname (string) – A string.denoting the name of the icon.

Notes: this method should be used to assign non-standard icon type to the annotation. See also: SetIcon() The annotation dictionary’s appearance stream, if present, will take precedence over this entry when displaying the annotation in the viewer.

e_Graph = 0

The icon has graph appearance

e_Paperclip = 2

The icon has a paper clip appearance

e_PushPin = 1

The icon has a push pin appearance.

e_Tag = 3

The icon has tag appearance

e_Unknown = 4

The icon has unrecognized appearance type

property thisown

The membership flag

apryse_sdk.FileAttachment_Create(args)

Overload 1:

Creates a file attachment annotation.

A file attachment annotation contains a reference to a file, which typically is embedded in the PDF file.

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds, in user space coordinates. Note that FileAttachment icons can differ in their appearance dimensions, so you may want to match these Rectangle dimensions or the aspect ratio to avoid a squished or stretched appearance: e_Graph: 40 x 40 e_PushPin: 28 x 40 e_Paperclip: 14 x 34 e_Tag: 40 x 32

• fs (FileSpec) – a file specification object used to initialize the file attachment annotation.

• icon_name (int) – The name of an icon to be used in displaying the annotation, default is PushPin.

Notes: PDF Viewer applications should provide predefined icon appearances for at least the following standard names: Graph, PushPin, Paperclip, Tag. Additional names may be supported as well. Default value: PushPin.

Return type:

FileAttachment

Returns:

A new file attachment annotation.

Overload 2:

Creates a file attachment annotation.

A file attachment annotation contains a reference to a file, which typically is embedded in the PDF file.

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds, in user space coordinates. Note that FileAttachment icons can differ in their appearance dimensions, so you may want to match these Rectangle dimensions or the aspect ratio to avoid a squished or stretched appearance: e_Graph: 40 x 40 e_PushPin: 28 x 40 e_Paperclip: 14 x 34 e_Tag: 40 x 32

• path (string) – The path to the file which should be attached

• icon_name (int) – An icon to be used in displaying the annotation, default is PushPin.

Notes: PDF Viewer applications should provide predefined icon appearances for at least the following standard names: Graph PushPin Paperclip Tag. Additional names may be supported as well. Default value: PushPin.

Return type:

FileAttachment

Returns:

A new file attachment annotation.

Overload 3:

Creates a file attachment annotation.

A file attachment annotation contains a reference to a file, which typically is embedded in the PDF file.

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds, in user space coordinates. Note that FileAttachment icons can differ in their appearance dimensions, so you may want to match these Rectangle dimensions or the aspect ratio to avoid a squished or stretched appearance: e_Graph: 40 x 40 e_PushPin: 28 x 40 e_Paperclip: 14 x 34 e_Tag: 40 x 32

• path (string) – The path to the file which should be attached

• icon_name – An icon to be used in displaying the annotation, default is PushPin.

Notes: PDF Viewer applications should provide predefined icon appearances for at least the following standard names: Graph PushPin Paperclip Tag. Additional names may be supported as well. Default value: PushPin.

Return type:

FileAttachment

Returns:

A new file attachment annotation.

Overload 4:

Creates a file attachment annotation. This method should be used when a nonstandard icon type is desired in the annotation.

A file attachment annotation contains a reference to a file, which typically is embedded in the PDF file.

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds, in user space coordinates.

• path (string) – The path to the file which should be attached

• icon_name (string) – The name of an icon to be used in displaying the annotation.

Notes: PDF Viewer applications should provide predefined icon appearances for at least the following standard names: Graph PushPin Paperclip Tag. Additional names may be supported as well. Default value: PushPin.

Return type:

FileAttachment

Returns:

A new file attachment annotation.

apryse_sdk.FileAttachment_CreateAnnot(args)

class apryse_sdk.FileSpec(args)

Bases: object

FileSpec corresponds to the PDF file specification object.

A PDF file can refer to the contents of another file by using a file specification, which can take either of the following forms:

• A simple file specification gives just the name of the target file in a standard format, independent of the naming conventions of any particular file system.

• A full file specification includes information related to one or more specific file systems.

• A URL reference.

Although the file designated by a file specification is normally external to the PDF file referring to it, it is also possible to embed the file allowing its contents to be stored or transmitted along with the PDF file. However, embedding a file does not change the presumption that it is external to (or separate from) the PDF file.

For more details on file specifications, please refer to Section 3.10, ‘File Specifications’ in the PDF Reference Manual.

static Create(doc, path, embed=True)

Creates a file specification for the given file. By default, the specified file is embedded in PDF.

Parameters:

• doc (SDFDoc) –

  • A document to which the FileSpec should be added. To obtain

  SDFDoc from PDFDoc use PDFDoc::GetSDFDoc() or Obj::GetDoc().

• path (string) –

  • The path to convert into a file specification.

• embed (boolean) –

  • A flag indicating whether to embed specified in the PDF.

  By default, all files are embedded.

Return type:

FileSpec

Returns:

newly created FileSpec object.

static CreateURL(doc, url)

Creates a URL file specification.

Parameters:

• doc (SDFDoc) –

  • A document to which the FileSpec should be added. To obtain

  SDFDoc from PDFDoc use PDFDoc::GetSDFDoc() or Obj::GetDoc().

• url (string) –

  • A uniform resource locator (URL) of the form defined in

  Internet RFC 1738, Uniform Resource Locators Specification.

Return type:

FileSpec

Returns:

newly created FileSpec object.

Export(args)

The function saves the data referenced by this FileSpec to an external file.

Parameters:

save_as (string) – An optional parameter indicating the filepath and filename where the data should be saved. If this parameter is not specified, the function will attempt to save the file using FileSpec.GetFilePath().

If the file is embedded, the function saves the embedded file. If the file is not embedded, the function will copy the external file. If the file is not embedded and the external file can’t be found, the function returns false.

Return type:

boolean

Returns:

true is the file was saved successfully, false otherwise.

GetFileData()

The function returns data referenced by this FileSpec.

Return type:

Filter

Returns:

A stream (filter) containing file data. If the file is embedded, the function returns a stream to the embedded file. If the file is not embedded, the function will return a stream to the external file. If the file is not embedded and the external file can’t be found, the function returns NULL.

GetFilePath()

Return type:

string

Returns:

The file path for this file specification.

If the FileSpec is a dictionary, a corresponding platform specific path is returned (DOS, Mac, or Unix). Otherwise the function returns the path represented in the form described in Section 3.10.1, ‘File Specification Strings,’ or , if the file system is URL, as a uniform resource locator (URL). If the FileSpec is not valid, an empty string is returned.

GetSDFObj()

Return type:

Obj

Returns:

The underlying SDF/Cos object.

IsValid()

Return type:

boolean

Returns:

whether this is a valid (non-null) FileSpec. If the function returns false the underlying SDF/Cos object is null or is not valid and the FileSpec object should be treated as null as well.

SetDesc(desc)

The functions sets the descriptive text associated with the file specification. This test is typically used in the EmbeddedFiles name tree.

property mp_impl

property thisown

The membership flag

apryse_sdk.FileSpec_Create(doc, path, embed=True)

Creates a file specification for the given file. By default, the specified file is embedded in PDF.

Parameters:

• doc (SDFDoc) –

  • A document to which the FileSpec should be added. To obtain

  SDFDoc from PDFDoc use PDFDoc::GetSDFDoc() or Obj::GetDoc().

• path (string) –

  • The path to convert into a file specification.

• embed (boolean) –

  • A flag indicating whether to embed specified in the PDF.

  By default, all files are embedded.

Return type:

FileSpec

Returns:

newly created FileSpec object.

apryse_sdk.FileSpec_CreateURL(doc, url)

Creates a URL file specification.

Parameters:

• doc (SDFDoc) –

  • A document to which the FileSpec should be added. To obtain

  SDFDoc from PDFDoc use PDFDoc::GetSDFDoc() or Obj::GetDoc().

• url (string) –

  • A uniform resource locator (URL) of the form defined in

  Internet RFC 1738, Uniform Resource Locators Specification.

Return type:

FileSpec

Returns:

newly created FileSpec object.

class apryse_sdk.Filter(args)

Bases: object

Provides a generic view of a sequence of bytes.

A Filter is the abstract base class of all filters. A filter is an abstraction of a sequence of bytes, such as a file, an input/output device, an inter-process communication pipe, or a TCP/IP socket. The Filter class and its derived classes provide a generic view of these different types of input and output, isolating the programmer from the specific details of the operating system and the underlying devices.

Besides providing access to input/output sources Filters can be also to transform the data (e.g. to compress the data stream, to normalize the image data, to encrypt data, etc). Filters can also be attached to each other to form pipelines. For example, a filter used to open an image data file can be attached to a filter that decompresses the data, which is attached to another filter that will normalize the image data.

Depending on the underlying data source or repository, filters might support only some of these capabilities. An application can query a stream for its capabilities by using the IsInputFilter() and CanSeek() properties.

Notes: To read or write data to a filter, a user will typically use FilterReader/FilterWriter class. instead of using Filter methods

For example:

StdFile file("my_stream.txt", StdFile::e_read_mode);
FilterReader reader(file);
while (reader.Read(..)) ...

AttachFilter(attach_filter)

Attaches a filter to the this filter. If this filter owns another filter it will be deleted. This filter then becomes the owner of the attached filter.

Parameters:

attach_filter (Filter) – filter object to attach

CanSeek()

Return type:

boolean

Returns:

• true if the stream supports seeking; otherwise, false.

default is to return false.

Consume(num_bytes)

Moves the Begin() pointer num_bytes forward.

Parameters:

num_bytes (int) –

• number of bytes to consume. num_bytes must be less than or

equal to Size().

Count()

Return type:

int

Returns:

• the number of bytes consumed since opening the filter or

the last Seek operation

CreateInputIterator()

Create Filter iterator. Filter iterator similar to a regular filter. However, there can be only one owner of the attached filter.

Notes: - Derived classes should make sure that there is only one owner of the

attached stream. Otherwise the attached stream may be deleted several times.

Raises:

• throws an exception if the method is not implemented in the derived class

Destroy()

Frees the native memory of the object.

Flush()

Forces any data remaining in the buffer to be written to input or output filter.

FlushAll()

Forces any data remaining in the filter chain to the source or destination.

GetAttachedFilter()

Return type:

Filter

Returns:

• returns attached Filter or a NULL filter if no filter is attached.

GetDecodeName()

Return type:

string

Returns:

• string representing the name of corresponding decode filter as

it should appear in document (e.g. both ASCIIHexDecode and ASCIIHexEncode should return ASCIIHexDecode).

GetFilePath()

Return type:

string

Returns:

the file path to the underlying file stream. Default implementation returns empty string.

GetName()

Return type:

string

Returns:

• descriptive name of the filter.

GetSourceFilter()

Return type:

Filter

Returns:

• returns the first filter in the chain (usually a file filter)

IsInputFilter()

Return type:

boolean

Returns:

• boolean indicating whether this is an input filter.

ReleaseAttachedFilter()

Release the ownership of the attached filter. After the attached filter is released this filter points to NULL filter.

Return type:

Filter

Returns:

• Previously attached filter.

Seek(offset, origin)

When overridden in a derived class, sets the position within the current stream.

Parameters:

• offset (ptrdiff_t) –

  • A byte offset relative to origin. If offset is negative,

  the new position will precede the position specified by origin by the number of bytes specified by offset. If offset is zero, the new position will be the position specified by origin. If offset is positive, the new position will follow the position specified by origin by the number of bytes specified by offset.

• origin (int) –

  • A value of type ReferencePos indicating the reference point used

  to obtain the new position

Notes: - After each Seek() operation the number of consumed bytes (i.e. Count()) is set to 0.

Raises:

• throws FilterExc if the method is not implemented in derived class

SetCount(new_count)

Sets a new counting point for the current filter. All subsequent Consume() operations will increment this counter.

Make sure that the output filter is flushed before using SetCount().

Parameters:

new_count (int) – number to set the counting point of the filter to.

Return type:

int

Returns:

• the value of previous counter

SetStreamLength(bytes)

The functions specifies the length of the data stream. The default implementation doesn’t do anything. For some derived filters such as file segment filter it may be useful to override this function in order to limit the stream length.

Parameters:

bytes (int) – the length of stream in bytes

Size()

Return type:

int

Returns:

• the size of buffer returned by Begin(). If the Size() returns 0

end of data has been reached.

Tell()

Reports the current read position in the stream relative to the stream origin.

Return type:

ptrdiff_t

Returns:

• The current position in the stream

Raises:

• throws FilterExc if the method is not implemented in derived class

Truncate(new_size)

Truncates the underlying data.

This method is for a writeable, seekable filter only and will throw otherwise.

Notes: For a filter representing a file, truncation would mean resizing the file.

Parameters:

new_size (int) –

• the number of bytes to resize the filter to

Return type:

int

Returns:

• The new size of the filter

Raises:

• throws FilterExc if the method is not implemented in derived class

WriteToFile(path, append)

Writes the entire filter, starting at current position, to specified filepath. Should only be called on an input filter.

type path:

string

Parameters:

• path –

  the output filepath.

  type append:

  boolean

• append – ‘true’ to append to existing file contents, ‘false’ to overwrite.

e_begin = 0

e_cur = 1

e_end = 2

property m_impl

property m_owner

property thisown

The membership flag

class apryse_sdk.FilterReader(args)

Bases: object

FilterReader is a utility class providing a convenient way to read data from an input filter (using Filter directly is not very intuitive).

For example:

StdFile file("my_stream.txt", StdFile::e_read_mode);
FilterReader reader(file);
while (reader.Read(...)) ...

AttachFilter(filter)

Attaches a filter to the this FilterReader.

Parameters:

filter (Filter) – filter object to attach

Count()

Return type:

int

Returns:

• the number of bytes consumed since opening the filter or

since the last Seek operation.

Flush()

Forces any data remaining in the buffer to be written to input or output filter.

FlushAll()

Forces any data remaining in the filter chain to the source or destination.

Get()

Return type:

int

Returns:

• the next character from the stream or EOF (-1) if the end of file is reached.

GetAttachedFilter()

Return type:

Filter

Returns:

• The attached Filter or a NULL filter if no filter is attached.

Peek()

Return type:

int

Returns:

• the next character without extracting it from the stream or

or EOF (-1) if the end of file is reached.

Read(buf_size)

Return type:

std::vector< unsigned char,std::allocator< unsigned char > >

Returns:

• returns the number of bytes actually read and stored in buffer (buf),

which may be less than buf_size if the end of the stream is encountered before reaching count.

Seek(offset, origin)

Sets the position within the current stream.

Parameters:

• offset (ptrdiff_t) –

  • A byte offset relative to origin. If offset is negative,

  the new position will precede the position specified by origin by the number of bytes specified by offset. If offset is zero, the new position will be the position specified by origin. If offset is positive, the new position will follow the position specified by origin by the number of bytes specified by offset.

• origin (int) –

  • A value of type ReferencePos indicating the reference point used

  to obtain the new position

Notes: - After each Seek() operation the number of consumed bytes (i.e. Count()) is set to 0. :raises: - throws an exception if the method is not implemented in the associated filter.

Tell()

Reports the current read position in the stream relative to the stream origin.

Return type:

ptrdiff_t

Returns:

• The current position in the stream

Raises:

• throws an exception if the method is not implemented in the associated filter.

property m_impl

property thisown

The membership flag

class apryse_sdk.FilterWriter(args)

Bases: object

FilterWriter is a utility class providing a convenient way to write data to an output filter (using Filter directly is not very intuitive).

For example:

StdFile outfile("file.dat", StdFile::e_write_mode);
FilterWriter fwriter(outfile);
fwriter.WriteBuffer(buf, buf_sz);
fwriter.Flush();

AttachFilter(filter)

Attaches a filter to the this FilterWriter.

Parameters:

filter (Filter) – filter object to attach

Count()

Return type:

int

Returns:

• the number of bytes consumed since opening the filter or

since the last Seek operation.

Flush()

Forces any data remaining in the buffer to be written to input or output filter.

FlushAll()

Forces any data remaining in the filter chain to the source or destination.

GetAttachedFilter()

Return type:

Filter

Returns:

• The attached Filter or a NULL filter if no filter is attached.

Seek(offset, origin)

Sets the position within the current stream.

Parameters:

• offset (ptrdiff_t) –

  • A byte offset relative to origin. If offset is negative,

  the new position will precede the position specified by origin by the number of bytes specified by offset. If offset is zero, the new position will be the position specified by origin. If offset is positive, the new position will follow the position specified by origin by the number of bytes specified by offset.

• origin (int) –

  • A value of type ReferencePos indicating the reference point used

  to obtain the new position

Notes: - After each Seek() operation the number of consumed bytes (i.e. Count()) is set to 0. :raises: - throws an exception if the method is not implemented in the associated filter.

Tell()

Reports the current read position in the stream relative to the stream origin.

Return type:

ptrdiff_t

Returns:

• The current position in the stream

Raises:

• throws an exception if the method is not implemented in the associated filter.

WriteBuffer(buf)

Parameters:

buf (std::vector< unsigned char,std::allocator< unsigned char > >) – buffer object to write out.

Return type:

int

Returns:

• returns the number of bytes actually written to a stream. This number may

less than buf_size if the stream is corrupted.

WriteFilter(reader)

Write the entire input stream to the output stream (i.e. to this FilterWriter).

Parameters:

reader (FilterReader) – A FilterReader attached to an input stream.

WriteInt16(num)

Write an integer to the output stream.

Parameters:

num (int) – An integer to write to the output stream.

WriteInt32(num)

WriteInt64(num)

WriteLine(line, eol=13)

Write out a null terminated ‘line’ followed by a end of line character default end of line character is carriage return.

Parameters:

• line (string) – string to write out.

• eol (char) – end of line character. Defaults to carriage return (0x0D).

WriteString(args)

Overload 1:

Write a string to the output stream.

Parameters:

str (string) – A string to write to the output stream.

Overload 2:

Write a null terminated string

Parameters:

str (string) – A terminated string string to write to the output stream.

WriteUChar(ch)

Write a single character to the output stream.

Parameters:

ch (UChar) – An unsigned character to write to the output stream.

WriteUInt16(num)

WriteUInt32(num)

WriteUInt64(num)

property m_impl

property thisown

The membership flag

class apryse_sdk.FlateEncode(input_filter, compression_level=-1, buf_sz=256)

Bases: Filter

FlateEncode filter can be used to compress any data stream using Flate (i.e. ZIP) compression method.

property thisown

The membership flag

class apryse_sdk.Flattener

Bases: object

Flattener is a optional PDFNet add-on that can be used to simplify and optimize existing PDF’s to render faster on devices with lower memory and speeds.

PDF documents can frequently contain very complex page description (e.g. thousands of paths, different shadings, color spaces, blend modes, large images etc.) that may not be suitable for interactive viewing on mobile devices. Flattener can be used to speed-up PDF rendering on mobile devices and on the Web by simplifying page content (e.g. flattening complex graphics into images) while maintaining vector text whenever possible.

By using the FlattenMode::e_simple option each page in the PDF will be reduced to a single background image, with the remaining text over top in vector format. Some text may still get flattened, in particular any text that is clipped, or underneath, other content that will be flattened.

On the other hand the FlattenMode::e_fast will not flatten simple content, such as simple straight lines, nor will it flatten Type3 fonts.

Notes: ‘Flattener’ is available as a separately licensable add-on to PDFNet core license.

See ‘pdftron.PDF.Optimizer’ for alternate approach to optimize PDFs with focus on file size reduction.

Destroy()

Frees the native memory of the object.

Process(args)

Overload 1:

Process each page in the PDF, flattening content that matches the mode criteria.

Parameters:

• doc (PDFDoc) – the document to flatten.

• mode (int) – indicates the criteria for which elements are flattened.

Overload 2:

Process the given page, flattening content that matches the mode criteria.

Parameters:

• page (Page) – the page to flatten.

• mode (int) – indicates the criteria for which elements are flattened.

SetDPI(dpi)

The output resolution, from 1 to 1000, in Dots Per Inch (DPI) at which to render elements which cannot be directly converted. the default value is 150 Dots Per Inch

Parameters:

dpi (int) – the resolution in Dots Per Inch

SetJPGQuality(quality)

Specifies the compression quality to use when generating JPEG images.

Parameters:

quality (int) – the JPEG compression quality, from 0(highest compression) to 100(best quality).

SetMaximumImagePixels(max_pixels)

Specifies the maximum image size in pixels.

Parameters:

max_pixels (int) – the maximum number of pixels an image can have.

SetPathHinting(enable_hinting)

Enable or disable path hinting.

Parameters:

enable_hinting (boolean) – if true path hinting is enabled. Path hinting is used to slightly adjust paths in order to avoid or alleviate artifacts of hair line cracks between certain graphical elements. This option is turned on by default.

SetPreferJPG(jpg)

Specifies whether to leave images in existing compression, or as JPEG.

Parameters:

jpg (boolean) – if true PDF will contain all JPEG images.

SetThreshold(threshold)

Used to control how precise or relaxed text flattening is. When some text is preserved (not flattened to image) the visual appearance of the document may be altered.

Parameters:

threshold (int) – the threshold setting to use.

e_fast = 1

Feature reduce PDF while trying to preserve some complex PDF features (such as vector figures, transparency, shadings, blend modes, Type3 fonts etc.) for pages that are already fast to render. This option can also result in smaller faster files compared to e_simple, but the pages may have more complex structure.

e_simple = 0

Feature reduce PDF to a simple two layer representation consisting of a single background RGB image and a simple top text layer.

e_threshold_default = 2

Render text that are somewhat clipped or occluded.

e_threshold_keep_all = 4

Only render text that are completely occluded, or used as a clipping path.

e_threshold_keep_most = 3

Only render text that are seriously clipped or occluded.

e_threshold_strict = 1

Render text that are marginally clipped or occluded.

e_threshold_very_strict = 0

Render (flatten) any text that is clipped or occluded.

property mp_impl

property thisown

The membership flag

class apryse_sdk.FlowDocument

Bases: object

The class FlowDocument. Encapsulates document creation API.

AddList()

Adds a list to the document.

Return type:

List

Returns:

The list object

AddParagraph(args)

Overload 1:

Adds a paragraph to the document.

Return type:

Paragraph

Returns:

The paragraph object

Overload 2:

Adds a paragraph to the document and sets the text.

Return type:

Paragraph

Returns:

The paragraph object

AddTable()

Adds a table to the document.

Return type:

Table

Returns:

The table object

GetBody()

Gets the body of the document.

The body is the root of the content tree. It can be used to traverse the content tree via the ContentNodeIterator object.

Return type:

ContentNode

Returns:

The body of the document

PaginateToPDF()

Paginates the content tree into a PDFDoc object.

Return type:

PDFDoc

Returns:

The PDFDoc object

SetDefaultMargins(left, top, right, bottom)

Set the default margins for the document.

Parameters:

• left (double) – The left margin in points

• top (double) – The top margin in points

• right (double) – The right margin in points

• bottom (double) – The bottom margin in points

SetDefaultPageSize(width, height)

Set the default page size for the document.

Parameters:

• width (double) – The width in points

• height (double) – The height in points

property m_impl

property thisown

The membership flag

class apryse_sdk.Font(args)

Bases: object

A font that is used to draw text on a page. It corresponds to a Font Resource in a PDF file. More than one page may reference the same Font object. A Font has a number of attributes, including an array of widths, the character encoding, and the font’s resource name.

PDF document can contain several different types of fonts and Font class represents a single, flat interface around all PDF font types.

There are two main classes of fonts in PDF: simple and composite fonts.

Simple fonts are Type1, TrueType, and Type3 fonts. All simple fonts have the following properties:

• Glyphs in the font are selected by single-byte character codes obtained from a string that is shown by the text-showing operators. Logically, these codes index into a table of 256 glyphs; the mapping from codes to glyphs is called the font’s encoding. Each font program has a built-in encoding. Under some circumstances, the encoding can be altered by means described in Section 5.5.5 “Character Encoding” in PDF Reference Manual.

• Each glyph has a single set of metrics. Therefore simple fonts support only horizontal writing mode.

A composite font is one whose glyphs are obtained from a font like object called a CIDFont (e.g. CIDType0Font and CIDType0Font). A composite font is represented by a font dictionary whose Subtype value is Type0. The Type 0 font is known as the root font, while its associated CIDFont is called its descendant. CID-keyed fonts provide a convenient and efficient method for defining multiple-byte character encodings and fonts with a large number of glyphs. These capabilities provide great flexibility for representing text in writing systems for languages with large character sets, such as Chinese, Japanese, and Korean (CJK).

static Create(args)

Overload 1:

Create a PDF::Font object for the given standard (also known as base 14 font)

Overload 2:

Create a CID TrueType PDF font with the characteristics specified in the LOGFONTA structure.

Parameters:

• doc (SDFDoc) –

  • document in which the external font should be embedded.

• logfonta – A pointer to a Windows LOGFONTA structure that defines the characteristics of the logical font.

• embed –

  • a boolean indicating whether the font should be embedded or

  not. For accurate font reproduction set the embed flag to ‘true’.

• subset –

  • a boolean indicating whether the embedded font should

  be subsetted

• encoding –

  • the encoding type either e_IdentityH (default)

  or e_Indices (to write glyph indices rather than unicode)

Notes: This method is available only on Windows platforms.

Create a CID TrueType PDF font with the characteristics specified in the LOGFONTA structure.

Parameters:

• doc (SDFDoc) –

  • document in which the external font should be embedded.

• logfontw – A pointer to a Windows LOGFONTW structure that defines the characteristics of the logical font.

• embed –

  • a boolean indicating whether the font should be embedded or

  not. For accurate font reproduction set the embed flag to ‘true’.

• subset –

  • a boolean indicating whether the embedded font should

  be subsetted

• encoding –

  • the encoding type either e_IdentityH (default)

  or e_Indices (to write glyph indices rather than unicode)

This method is available only on Windows platforms.

Create a new Unicode font based on the description of an existing PDF font.

Parameters:

• doc (SDFDoc) – document in which the external font should be embedded.

• from (Font) – A Font object that provides the name for choosing a font. If the font with that name can be located and it covers a sufficient character set characters from that font will be used. Otherwise the font object created will be from a another font that covers the character set.

• char_set (string) – An initial character set. This provides an approach to specify any characters that are required to be included in the final font as part of a string. Note that additional characters will be added to the character set as needed, so it is not required to specify them here. (empty string is a perfectly valid and common value for this argument)

Overload 3:

Create a new Unicode font based on the description of an existing PDF font.

Parameters:

• doc (SDFDoc) – document in which the external font should be embedded.

• name (string) – A font name that provides a hint when choosing a font. If the font with that name can be located and it covers a sufficient character set characters from that font will be used. Otherwise the font object created will be from a another font that covers the character set.

• char_set (string) – An initial character set. This provides an approach to specify any characters that are required to be included in the final font as part of a string. Note that additional characters will be added to the character set as needed, so it is not required to specify them here. (empty string is a perfectly valid and common value for this argument)

static CreateCIDTrueTypeFont(args)

Embed an external TrueType font in the document as a CID font. By default the function selects “Identity-H” encoding that maps 2-byte character codes ranging from 0 to 65,535 to the same Unicode value. Other predefined encodings are listed in Table 5.15 ‘Predefined CMap names’ in PDF Reference Manual.

Parameters:

• doc (SDFDoc) –

  • document in which the external font should be embedded.

• font_path (string) –

  • path to the external font file.

• embed (boolean) –

  • a boolean indicating whether the font should be embedded or

  not. For accurate font reproduction set the embed flag to ‘true’.

• subset (boolean) –

  • a boolean indicating whether the embedded font should

  be subsetted

• encoding (int) –

  • the encoding type either e_IdentityH (default)

  or e_Indices (to write glyph indices rather than unicode)

• ttc_font_index (int) –

  • if a TrueTypeCollection (TTC) font is loaded this

  parameter controls which font is actually picked

static CreateTrueTypeFont(doc, font_path, embed=True, subset=True)

Embed an external TrueType font in the document as a Simple font.

Notes: glyphs in the Simple font are selected by single-byte character codes. If you want to work with multi-byte character codes (e.g. UTF16) you need to create a CID font.

Parameters:

• doc (SDFDoc) – Document in which the external font should be embedded.

• font_path (string) – Path to the external font file.

• embed (boolean) – A boolean indicating whether the font should be embedded or not. For accurate font reproduction set the embed flag to ‘true’.

• subset (boolean) – A boolean indicating whether the embedded font should be subsetted.

static CreateType1Font(doc, font_path, embed=True)

Embed an external Type1 font in the document.

Parameters:

• doc (SDFDoc) –

  • document in which the external font should be embedded.

• font_path (string) –

  • path to the external font file.

• embed (boolean) –

  • a boolean indicating whether the font should be embedded or

  not. For accurate font reproduction set the embed flag to ‘true’.

Destroy()

Frees the native memory of the object.

GetAscent()

The face’s ascender is the vertical distance from the baseline to the topmost point of any glyph in the face. This field’s value is a positive number, expressed in the glyph coordinate system. For all font types except Type 3, the units of glyph space are one-thousandth of a unit of text space. Some font designs use a value different from ‘bbox.yMax’.

Notes: Only relevant for scalable formats.

GetBBox()

Return type:

Rect

Returns:

A rectangle expressed in the glyph coordinate system, specifying the font bounding box. This is the smallest rectangle enclosing the shape that would result if all of the glyphs of the font were placed with their origins coincident and then filled.

GetCharCodeIterator()

GetCharCodeIterator represents an iterator interface used to traverse a list of char codes for which there is a glyph outline in the embedded font.

GetDescendant()

Return type:

Font

Returns:

descendant CIDFont.

Notes: Relevant only for a Type0 font.

GetDescent()

The face’s descender is the vertical distance from the baseline to the bottommost point of any glyph in the face. This field’s value is a negative number expressed in the glyph coordinate system. For all font types except Type 3, the units of glyph space are one-thousandth of a unit of text space. Some font designs use a value different from ‘bbox.yMin’.

Notes: Only relevant for scalable formats.

GetDescriptor()

Return type:

Obj

Returns:

a SDF/Cos object representing FontDescriptor or NULL is FontDescriptor is not present.

GetEmbeddedFont()

Return type:

Obj

Returns:

the stream object of the embedded font or NULL if there if the font is not embedded.

Notes: This function is not applicable to Type3 font and will throw exception.

GetEmbeddedFontBufSize()

Return type:

int

Returns:

the size of decoded buffer containing embedded font data or 0 if this information is not known in advance.

Notes: The size of decoded buffer may not be known in advance for all fonts and may not be correct. This function is not applicable to Type3 font and will throw exception.

GetEmbeddedFontName()

Return type:

string

Returns:

the PostScript font name for the embedded font. If the embedded font name is not available the function returns the empty string .

GetFamilyName()

Return type:

string

Returns:

the face’s family name. This is an ASCII string, usually in English, which describes the typeface’s family (like ‘Times New Roman’, ‘Bodoni’, ‘Garamond’, etc). This is a least common denominator used to list fonts.

GetGlyphPath(char_code, conics2cubics, transform=None)

The function retrieves the glyph outline for a given character code.

Parameters:

• char_code (int) – character to query

• conics2cubics (boolean) – if set to true converts all quadratic Bezier curves to cubic Beziers, otherwise no conversion is performed.

• transform (Matrix2D) – An optional matrix used to transform glyph data coordinates. If null/unspecified, glyph data points will not be transformed.

Return type:

PathData

Returns:

A PathData object containing the path information.

Notes: the function can return only the following operators (Element::e_moveto, Element::e_lineto, Element::e_cubicto and optionally Element::e_conicto if conics2cubics parameter is set to true.

This function is not applicable to Type3 font and will throw an exception. Use GetType3GlyphStream instead.

Check PathData::IsDefined to see if the char_code was mapped to ‘undefined character code’.

GetMaxWidth()

Return type:

double

Returns:

the maximal advance width, in font units, for all glyphs in this face.

GetMissingWidth()

Return type:

double

Returns:

the default width to use for character codes whose widths are not specified in a font dictionary’s Widths array.

GetName()

Return type:

string

Returns:

the name of a font. The behavior depends on the font type; for a Type 3 font it gets the value of the Name key in a PDF Font resource. For other types it gets the value of the BaseFont key in a PDF font resource.

GetSDFObj()

Return type:

Obj

Returns:

a SDF/Cos object of this Font.

GetShapedText(text_to_shape)

Creates a set of positioned glyphs corresponding to the visual representation of the provided text string.

The shaped text will take into account any advanced positioning and substitution features provided by an underylying embedded font file. For example, these features could include kerning, ligatures, and diacritic positioning. Typically the resulting shaped text would be fed into ElementBuilder.CreateShapedTextRun()

Parameters:

text_to_shape (string) – the string to be shaped.

Return type:

ShapedText

Returns:

A ShapedText object representing the result of the shaping operation.

Notes: Shaping requires a Type0 font with an embedded font file which covers all the unicode codepoints in the source text. For best results, this font should use the e_Indices encoding scheme, as shaping features that combine multiple codepoints into one glyph (ligatures, for example) will not work well in non-index encoded fonts.

GetStandardType1FontType()

Return type:

int

Returns:

Font::e_null if the font is not a standard Type1 font or some other StandardType1Font value for a standard Type1 font.

GetType()

Return type:

int

Returns:

Font Type

GetType3FontMatrix()

Return type:

Matrix2D

Returns:

Type3 font matrix, mapping glyph space to text space A common practice is to define glyphs in terms of a 1000-unit glyph coordinate system, in which case the font matrix is [0.001 0 0 0.001 0 0].

Notes: Relevant only for a Type3 font.

GetType3GlyphStream(char_code)

Return type:

Obj

Returns:

a SDF/Cos glyph stream for the given char_code. If specified char_code is not found in the CharProcs dictionary the function returns NULL.

Notes: Relevant only for a Type3 font.

GetUnitsPerEm()

Return type:

int

Returns:

the number of font units per EM square for this face. This is typically 2048 for TrueType fonts, 1000 for Type1 fonts

Notes: Only relevant for scalable formats (such as TrueType and Type1).

This function is not applicable to Type3 font and will throw an exception. Use GetType3FontMatrix instead.

GetVerticalAdvance(char_code)

Return type:

std::vector< double,std::allocator< double > >

Returns:

vertical advance. vertical advance is a displacement vector for vertical writing mode (i.e. writing mode 1); its horizontal component is always 0.

Parameters:

• char_code (int) – character to query for vertical advance

• out_pos_vect_x –

  • initialized by the method. horizontal component of the

  position vector defining the position of the vertical writing mode origin relative to horizontal writing mode origin.

• out_pos_vect_y –

  • initialized by the method. vertical component of the

  position vector defining the position of the vertical writing mode origin relative to horizontal writing mode origin.

Notes: Use this method only for composite fonts with vertical writing mode (i.e. if Font.IsHorizontalMode() returns false). The method will return 0 as vertical advance for simple fonts or for composite fonts with only horizontal writing mode. Relevant only for a Type0 font.

GetWidth(char_code)

Return type:

double

Returns:

advance width, measured in glyph space units for the glyph matching given character code.

Notes: 1000 glyph units = 1 text space unit The width returned has NOT been scaled by the font size, text matrix,

nor the CTM.

The function gets the advance width of the font glyph. The advance width is the amount by which the current point advances when the glyph is drawn. The advance width may not correspond to the visible width of the glyph and for this reason, the advance width cannot be used to determine the glyphs’ bounding boxes.

IsAllCap()

Return type:

boolean

Returns:

true if font contains no lowercase letters

IsCFF()

Return type:

boolean

Returns:

true if the embedded font is represented as CFF (Compact Font Format).

Notes: Only Type1 and Type1C fonts can be represented in CFF format

IsEmbedded()

Tests whether or not the specified font is stored as a font file in a stream embedded in the PDF file.

Return type:

boolean

Returns:

true if the font is embedded in the file, false otherwise.

IsFixedWidth()

Return type:

boolean

Returns:

true if all glyphs have the same width

IsForceBold()

Return type:

boolean

Returns:

true if bold glyphs should be painted with extra pixels at very small text sizes.

IsHorizontalMode()

Return type:

boolean

Returns:

true if the font uses horizontal writing mode, false for vertical writing mode.

IsItalic()

Return type:

boolean

Returns:

true if glyphs have dominant vertical strokes that are slanted.

IsSerif()

Return type:

boolean

Returns:

true if glyphs have serifs

IsSimple()

Return type:

boolean

Returns:

true for non-CID based fonts such as Type1, TrueType, and Type3

All simple fonts have the following properties:

• Glyphs in the font are selected by single-byte character codes obtained from a string that is shown by the text-showing operators. Logically, these codes index into a table of 256 glyphs; the mapping from codes to glyphs is called the font’s encoding. Each font program has a built-in encoding. Under some circumstances, the encoding can be altered by means described in Section 5.5.5 “Character Encoding” in PDF Reference Manual.

• Each glyph has a single set of metrics. Therefore simple fonts support only horizontal writing mode.

IsSymbolic()

Return type:

boolean

Returns:

true if font contains characters outside the Adobe standard Latin character set.

MapToCID(char_code)

Return type:

int

Returns:

a CID matching specified charcode.

Notes: Relevant only for a Type0 font.

MapToUnicode(char_code)

Maps the encoding specific ‘charcode’ to Unicode. Conversion of ‘charcode’ to Unicode can result in up to four Unicode characters.

Parameters:

• char_code (int) – encoding specific ‘charcode’ that needs to be converted to Unicode.

• out_uni_arr – A pointer to an array of Unicode characters where the conversion result will be stored.

• in_uni_sz – The number of characters that can be written to out_uni_arr. You can assume that the function will never map to more than 10 characters.

• out_char_num – The function will modify this value to return the number of Unicode characters written in ‘out_uni_arr’ array.

Return type:

string

Returns:

true if char_code was mapped to Unicode public area or false if the char_code was mapped to Unicode private area.

A char_code is mapped to Unicode private area when the information required for proper mapping is missing in PDF document (e.g. a predefined encoding or ToUnicode CMap).

Notes: This function is not applicable to CIDFonts (e_CIDType0 and e_CIDType2) and will throw an exception if called.

e_CIDType0 = 5

e_CIDType2 = 6

e_IdentityH = 0

e_Indices = 1

e_MMType1 = 2

e_TrueType = 1

e_Type0 = 4

e_Type1 = 0

e_Type3 = 3

e_courier = 8

e_courier_bold = 9

e_courier_bold_oblique = 11

e_courier_oblique = 10

e_helvetica = 4

e_helvetica_bold = 5

e_helvetica_bold_oblique = 7

e_helvetica_oblique = 6

e_null = 14

e_symbol = 12

e_times_bold = 1

e_times_bold_italic = 3

e_times_italic = 2

e_times_roman = 0

e_zapf_dingbats = 13

property mp_font

property thisown

The membership flag

apryse_sdk.Font_Create(args)

Overload 1:

Create a PDF::Font object for the given standard (also known as base 14 font)

Overload 2:

Create a CID TrueType PDF font with the characteristics specified in the LOGFONTA structure.

Parameters:

• doc (SDFDoc) –

  • document in which the external font should be embedded.

• logfonta – A pointer to a Windows LOGFONTA structure that defines the characteristics of the logical font.

• embed –

  • a boolean indicating whether the font should be embedded or

  not. For accurate font reproduction set the embed flag to ‘true’.

• subset –

  • a boolean indicating whether the embedded font should

  be subsetted

• encoding –

  • the encoding type either e_IdentityH (default)

  or e_Indices (to write glyph indices rather than unicode)

Notes: This method is available only on Windows platforms.

Create a CID TrueType PDF font with the characteristics specified in the LOGFONTA structure.

Parameters:

• doc (SDFDoc) –

  • document in which the external font should be embedded.

• logfontw – A pointer to a Windows LOGFONTW structure that defines the characteristics of the logical font.

• embed –

  • a boolean indicating whether the font should be embedded or

  not. For accurate font reproduction set the embed flag to ‘true’.

• subset –

  • a boolean indicating whether the embedded font should

  be subsetted

• encoding –

  • the encoding type either e_IdentityH (default)

  or e_Indices (to write glyph indices rather than unicode)

This method is available only on Windows platforms.

Create a new Unicode font based on the description of an existing PDF font.

Parameters:

• doc (SDFDoc) – document in which the external font should be embedded.

• from (Font) – A Font object that provides the name for choosing a font. If the font with that name can be located and it covers a sufficient character set characters from that font will be used. Otherwise the font object created will be from a another font that covers the character set.

• char_set (string) – An initial character set. This provides an approach to specify any characters that are required to be included in the final font as part of a string. Note that additional characters will be added to the character set as needed, so it is not required to specify them here. (empty string is a perfectly valid and common value for this argument)

Overload 3:

Create a new Unicode font based on the description of an existing PDF font.

Parameters:

• doc (SDFDoc) – document in which the external font should be embedded.

• name (string) – A font name that provides a hint when choosing a font. If the font with that name can be located and it covers a sufficient character set characters from that font will be used. Otherwise the font object created will be from a another font that covers the character set.

• char_set (string) – An initial character set. This provides an approach to specify any characters that are required to be included in the final font as part of a string. Note that additional characters will be added to the character set as needed, so it is not required to specify them here. (empty string is a perfectly valid and common value for this argument)

apryse_sdk.Font_CreateCIDTrueTypeFont(args)

Embed an external TrueType font in the document as a CID font. By default the function selects “Identity-H” encoding that maps 2-byte character codes ranging from 0 to 65,535 to the same Unicode value. Other predefined encodings are listed in Table 5.15 ‘Predefined CMap names’ in PDF Reference Manual.

Parameters:

• doc (SDFDoc) –

  • document in which the external font should be embedded.

• font_path (string) –

  • path to the external font file.

• embed (boolean) –

  • a boolean indicating whether the font should be embedded or

  not. For accurate font reproduction set the embed flag to ‘true’.

• subset (boolean) –

  • a boolean indicating whether the embedded font should

  be subsetted

• encoding (int) –

  • the encoding type either e_IdentityH (default)

  or e_Indices (to write glyph indices rather than unicode)

• ttc_font_index (int) –

  • if a TrueTypeCollection (TTC) font is loaded this

  parameter controls which font is actually picked

apryse_sdk.Font_CreateTrueTypeFont(doc, font_path, embed=True, subset=True)

Embed an external TrueType font in the document as a Simple font.

Notes: glyphs in the Simple font are selected by single-byte character codes. If you want to work with multi-byte character codes (e.g. UTF16) you need to create a CID font.

Parameters:

• doc (SDFDoc) – Document in which the external font should be embedded.

• font_path (string) – Path to the external font file.

• embed (boolean) – A boolean indicating whether the font should be embedded or not. For accurate font reproduction set the embed flag to ‘true’.

• subset (boolean) – A boolean indicating whether the embedded font should be subsetted.

apryse_sdk.Font_CreateType1Font(doc, font_path, embed=True)

Embed an external Type1 font in the document.

Parameters:

• doc (SDFDoc) –

  • document in which the external font should be embedded.

• font_path (string) –

  • path to the external font file.

• embed (boolean) –

  • a boolean indicating whether the font should be embedded or

  not. For accurate font reproduction set the embed flag to ‘true’.

class apryse_sdk.FreeText(args)

Bases: Markup

A FreeText annotation (PDF 1.3) displays text directly on the page. Unlike an ordinary Text annotation, a FreeText annotation has no open or closed state; The content of the FreeText annotation is always visible instead of being displayed in a popup window.

static Create(doc, pos)

Creates a new FreeText annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the FreeText annotation is added.

• pos (Rect) – A rectangle specifying the FreeText annotation’s bounds in default user space units.

Return type:

FreeText

Returns:

A newly created blank FreeText annotation.

static CreateAnnot(doc, pos)

GetCalloutLinePoint1()

Returns the callout line points of the FreeText annotation. (PDF 1.6)

Parameters:

• p1 – The target point. (where the ending style is used)

• p2 – The ending point.

• p3 – The knee point.

Return type:

Point

Returns:

Three point objects if the line is bent or two point objects if the line is straight.

Notes: If the line is straight, i.e. only has two points, two points will be returned in p1 and p2, and p3 will be the same as p2. The coordinates are given in default user space.

GetCalloutLinePoint2()

GetCalloutLinePoint3()

GetDefaultAppearance()

Returns the default appearance of the FreeText annotation.

Return type:

string

Returns:

A string representing the default appearance of the annotation.

Notes: The default appearance string is used to format the text. The annotation dictionary’s Appearance entry, if present, will take precedence over this entry. this method corresponds to the ‘DA’ entry in the annotation dictionary.

GetEndingStyle()

Returns the ending style of the callout line of the FreeText Annotation.

Return type:

int

Returns:

The ending style represented as one of the entries of the enum “EndingStyle”

Notes: The ending style specifies the line ending style that shall be used in drawing the callout line specified in CallOut Line Points (CL). The enum entry shall specify the line ending style for the endpoint defined by the target point(p1) of the CallOut Line Points. Default value: e_None.

GetFontSize()

Get the default appearance font size. To get the actual font size used, call RefreshAppearance and then use ElementReader on the content stream of this annotation.

Return type:

double

Returns:

the default font size, where a value of zero indicates auto sizing.

GetIntentName()

Returns Intent name of the FreeText annotation. (PDF 1.4)

Return type:

int

Returns:

The intent name of the annotation as an entry from the enum “IntentName”.

GetLineColor()

Returns the line and border color of the FreeText Annotation.

Parameters:

• color – reference to ColorPt object, where results will be saved.

• col_comp – reference to an integer, where number of colorant components will be written.

Notes: Current implementation of this method uses a non-standard entry in the annotation dictionary and will not return meaningful results when called on annotations not created with PDFTron software.

GetLineColorCompNum()

GetQuaddingFormat()

Returns the quading format of the FreeText annotation. (PDF 1.4)

Return type:

int

Returns:

A int (code) indicating the quading format of the FreeText annotation.

Notes: The following are the quading formats corresponding to each int code. 0 Left-justified 1 Centered 2 Right-justified

GetTextColor()

Returns the text color of the FreeText Annotation.

Notes: Current implementation of this method uses a non-standard entry in the annotation dictionary and will not return meaningful results when called on annotations not created with PDFTron software.

GetTextColorCompNum()

SetCalloutLinePoints(args)

Overload 1:

Sets the callout line points of the FreeText annotation. (Optional; meaningful only if IT is FreeTextCallout; PDF 1.6)

Parameters:

• p1 (Point) – The target point. (where the ending style is used)

• p2 (Point) – The knee point.

• p3 (Point) – The ending point.

Notes: The coordinates are defined in default user space.

Overload 2:

Sets the callout line points of the FreeText annotation. (Optional; meaningful only if IT is FreeTextCallout; PDF 1.6)

Parameters:

• p1 (Point) – The target point. (where the ending style is used)

• p2 (Point) – The ending point.

Notes: The coordinates are defined in default user space.

SetDefaultAppearance(app_str)

Sets the default appearance of the FreeText annotation.

Parameters:

app_str (string) – A string representing the default appearance of the annotation.

Notes: The default appearance string is used to format the text. The annotation dictionary’s Appearance entry, if present, will take precedence over this entry. this method corresponds to the ‘DA’ entry in the annotation dictionary.

SetEndingStyle(args)

Overload 1:

Sets the ending style of the callout line of the FreeText Annotation. (Optional; meaningful only if CL is present; PDF 1.6)

Parameters:

style (int) – The ending style represented using one of the entries of the enum “EndingStyle”

Notes: The ending style specifies the line ending style that shall be used in drawing the callout line specified in CallOut Line Points (CL). The enum entry shall specify the line ending style for the endpoint defined by the target point(p1) of the CallOut Line Points. Default value: e_None.

Overload 2:

Sets the ending style of the callout line of the FreeText Annotation. (Optional; meaningful only if CL is present; PDF 1.6)

Parameters:

est (string) – The ending style represented using a string.

Notes: The ending style specifies the line ending style that shall be used in drawing the callout line specified in CallOut Line Points (CL). The enum entry shall specify the line ending style for the endpoint defined by the target point(p1) of the CallOut Line Points. Default value: “None”.

SetFontName(fontName)

Sets the default appearance font name.

Parameters:

fontName (string) – Set the default name name.

SetFontSize(font_size)

Sets the default appearance font size. A value of zero specifies that the font size should should adjust so that the text uses as much of the FreeText bounding box as possible.

Parameters:

font_size (double) – Set the default font size. A value of zero means auto resize font.

SetIntentName(args)

Sets the Intent name of the FreeText annotation. (Optional; PDF 1.4)

Parameters:

mode (int) – The intent name of the annotation as an entry from the enum “IntentName”.

SetLineColor(color, col_comp)

Sets the line and border color of the FreeText Annotation.

Parameters:

• color (ColorPt) – ColorPt object representing the color.

• col_comp (int) – number of colorant components in ColorPt object.

Notes: Current implementation of this method creates a non-standard entry in the annotation dictionary and uses it to generate the appearance stream. Make sure you call RefreshAppearance() after changing text or line color, and remember that editing the annotation in other PDF applications will produce different appearance.

SetQuaddingFormat(format)

Sets the quading format of the FreeText annotation. (Optional; PDF 1.4)

Parameters:

format (int) – A int code indicating the quading format of the FreeText annotation. Default value: 0 (left-justified).

Notes: The int code specifies the form of quadding (justification) that shall be used in displaying the annotation’s text: 0 Left-justified 1 Centered 2 Right-justified

SetTextColor(color, col_comp)

Sets the text color of the FreeText Annotation.

Parameters:

• color (ColorPt) – ColorPt object representing the color.

• col_comp (int) – number of colorant components in ColorPt object.

Notes: Current implementation of this method creates a non-standard entry in the annotation dictionary and uses it to generate the appearance stream. Make sure you call RefreshAppearance() after changing text or line color, and remember that editing the annotation in other PDF applications will produce different appearance.

e_FreeText = 0

The annotation intended to function as a plain FreeText annotation.

e_FreeTextCallout = 1

The annotation is intended to function as a callout.

e_FreeTextTypeWriter = 2

The annotation is intended to function as a click-to-type or typewriter object and no callout line is drawn.

e_Unknown = 3

User defined or Invalid.

property thisown

The membership flag

apryse_sdk.FreeText_Create(doc, pos)

Creates a new FreeText annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the FreeText annotation is added.

• pos (Rect) – A rectangle specifying the FreeText annotation’s bounds in default user space units.

Return type:

FreeText

Returns:

A newly created blank FreeText annotation.

apryse_sdk.FreeText_CreateAnnot(doc, pos)

class apryse_sdk.Function(args)

Bases: object

Although PDF is not a programming language it provides several types of function object that represent parameterized classes of functions, including mathematical formulas and sampled representations with arbitrary resolution. Functions are used in various ways in PDF, including device-dependent rasterization information for high-quality printing (halftone spot functions and transfer functions), color transform functions for certain color spaces, and specification of colors as a function of position for smooth shadings. Functions in PDF represent static, self-contained numerical transformations.

PDF::Function represents a single, flat interface around all PDF function types.

Destroy()

Frees the native memory of the object.

Eval(in_arr)

Evaluate the function at a given point.

Notes: that size of ‘in’ array must be greater than or equal to function input cardinality. and the size of ‘out’ array must be greater than or equal to function output cardinality.

GetInputCardinality()

Return type:

int

Returns:

the number of input components required by the function

GetOutputCardinality()

Return type:

int

Returns:

the number of output components returned by the function

GetSDFObj()

Return type:

Obj

Returns:

the underlying SDF/Cos object

GetType()

Return type:

int

Returns:

The function type

e_exponential = 2

e_postscript = 4

e_sampled = 0

e_stitching = 3

property mp_func

property thisown

The membership flag

class apryse_sdk.GSChangesIterator(args)

Bases: object

The Iterator specialization for integer type.

Current()

Destroy()

Frees the native memory of the object.

HasNext()

Next()

property mp_impl

property thisown

The membership flag

class apryse_sdk.GState(args)

Bases: object

GState is a class that keeps track of a number of style attributes used to visually define graphical Elements. Each PDF::Element has an associated GState that can be used to query or set various graphics properties.

Notes: current clipping path is not tracked in the graphics state for efficiency reasons. In most cases tracking of the current clipping path is best left to the client.

Concat(args)

Overload 1:

Concatenate the given matrix to the transformation matrix of this element.

Parameters:

mtx (Matrix2D) – Matrix2D object to concatenate the current matrix with.

Overload 2:

Concatenate the given matrix expressed in its values to the transformation matrix of this element.

Parameters:

• a (double) –

  • horizontal ‘scaling’ component of the new text matrix.

• b (double) –

  • ‘rotation’ component of the new text matrix.

• c (double) –

  • ‘rotation’ component of the new text matrix.

• d (double) –

  • vertical ‘scaling’ component of the new text matrix.

• h (double) –

  • horizontal translation component of the new text matrix.

• v (double) –

  • vertical translation component of the new text matrix.

GetAISFlag()

Return type:

boolean

Returns:

the alpha source flag (‘alpha is shape’), specifying whether the current soft mask and alphaant are to be interpreted as shape values (true) or opacity values (false).

GetAutoStrokeAdjust()

Return type:

boolean

Returns:

a flag specifying whether stroke adjustment is enabled in the graphics state. Corresponds to the /SA key within the ExtGState’s dictionary.

GetBlackGenFunct()

Return type:

Obj

Returns:

currently selected black-generation function (NULL by default) used during conversion between DeviceRGB and DeviceCMYK. Corresponds to the /BG key within the ExtGState’s dictionary.

GetBlendMode()

Return type:

int

Returns:

the current blend mode to be used in the transparent imaging model. Corresponds to the /BM key within the ExtGState’s dictionary.

GetCharSpacing()

Return type:

double

Returns:

currently selected character spacing.

The character spacing parameter is a number specified in unscaled text space units. When the glyph for each character in the string is rendered, the character spacing is added to the horizontal or vertical component of the glyph’s displacement, depending on the writing mode. See Section 5.2.1 in PDF Reference Manual for details.

GetDashes()

Return type:

std::vector< double,std::allocator< double > >

Returns:

The method fills the vector with an array of numbers representing the dash pattern

The line dash pattern controls the pattern of dashes and gaps used to stroke paths. It is specified by a dash array and a dash phase. The dash array’s elements are numbers that specify the lengths of alternating dashes and gaps; the dash phase specifies the distance into the dash pattern at which to start the dash. The elements of both the dash array and the dash phase are expressed in user space units.

GetFillColor()

Return type:

ColorPt

Returns:

a color value/point represented in the current fill color space

GetFillColorSpace()

Return type:

ColorSpace

Returns:

color space used for filling

GetFillOpacity()

Return type:

double

Returns:

the opacity value for painting operations other than stroking. Returns the value of the /ca key in the ExtGState dictionary. If the value is not found, the default value of 1 is returned.

GetFillOverprint()

Return type:

boolean

Returns:

whether overprint is enabled for fill painting operations. Corresponds to the /op key within the ExtGState’s dictionary.

GetFillPattern()

Return type:

PatternColor

Returns:

the pattern color of currently selected pattern color space used for filling.

GetFlatness()

Return type:

double

Returns:

current value of flatness tolerance

Flatness is a number in the range 0 to 100; a value of 0 specifies the output device’s default flatness tolerance.

The flatness tolerance controls the maximum permitted distance in device pixels between the mathematically correct path and an approximationructed from straight line segments.

GetFont()

Return type:

Font

Returns:

currently selected font

GetFontSize()

Return type:

double

Returns:

the font size

GetHalftone()

Return type:

Obj

Returns:

currently selected halftone dictionary or stream (NULL by default). Corresponds to the /HT key within the ExtGState’s dictionary. Halftoning is a process by which continuous-tone colors are approximated on an output device that can achieve only a limited number of discrete colors.

GetHorizontalScale()

Return type:

double

Returns:

currently selected horizontal scale

The horizontal scaling parameter adjusts the width of glyphs by stretching or compressing them in the horizontal direction. Its value is specified as a percentage of the normal width of the glyphs, with 100 being the normal width. The scaling always applies to the horizontal coordinate in text space, independently of the writing mode. See Section 5.2.3 in PDF Reference Manual for details.

GetLeading()

Return type:

double

Returns:

currently selected leading parameter

The leading parameter is measured in unscaled text space units. It specifies the vertical distance between the baselines of adjacent lines of text. See Section 5.2.4 in PDF Reference Manual for details.

GetLineCap()

Return type:

int

Returns:

currently selected LineCap style

The line cap style specifies the shape to be used at the ends of open sub-paths (and dashes, if any) when they are stroked.

GetLineJoin()

Return type:

int

Returns:

currently selected LineJoin style

The line join style specifies the shape to be used at the corners of paths that are stroked.

GetLineWidth()

Return type:

double

Returns:

the thickness of the line used to stroke a path.

Notes: A line width of 0 denotes the thinnest line that can be rendered at device resolution: 1 device pixel wide.

GetMiterLimit()

Return type:

double

Returns:

current value of miter limit.

The miter limit imposes a maximum on the ratio of the miter length to the line width. When the limit is exceeded, the join is converted from a miter to a bevel.

GetOverprintMode()

Return type:

int

Returns:

the overprint mode used by this graphics state. Corresponds to the /OPM key within the ExtGState’s dictionary.

GetPhase()

Return type:

double

Returns:

the phase of the currently selected dash pattern. dash phase is expressed in user space units.

GetRenderingIntent()

Return type:

int

Returns:

The color intent to be used for rendering the Element

static GetRenderingIntentType(name)

A utility function that maps a string representing a rendering intent to RenderingIntent type.

Parameters:

name (string) – string that represents the rendering intent to get.

Return type:

int

Returns:

The color rendering intent type matching the specified string

GetSmoothnessTolerance()

Return type:

double

Returns:

the smoothness tolerance used to control the quality of smooth shading. Corresponds to the /SM key within the ExtGState’s dictionary. The allowable error (or tolerance) is expressed as a fraction of the range of the color component, from 0.0 to 1.0.

GetSoftMask()

Return type:

Obj

Returns:

Associated soft mask. NULL if the soft mask is not selected or SDF dictionary representing the soft mask otherwise.

GetSoftMaskTransform()

Return type:

Matrix2D

Returns:

The soft mask transform. This is the transformation matrix at the moment the soft mask is established in the graphics state with the gs operator. This information is only relevant when applying the soft mask that may be specified in the graphics state to the current element.

GetStrokeColor()

Return type:

ColorPt

Returns:

a color value/point represented in the current stroke color space

GetStrokeColorSpace()

Return type:

ColorSpace

Returns:

color space used for stroking

GetStrokeOpacity()

Return type:

double

Returns:

opacity value for stroke painting operations for paths and glyph outlines. Returns the value of the /CA key in the ExtGState dictionary. If the value is not found, the default value of 1 is returned.

GetStrokeOverprint()

Return type:

boolean

Returns:

whether overprint is enabled for stroke painting operations. Corresponds to the /OP key within the ExtGState’s dictionary.

GetStrokePattern()

Return type:

PatternColor

Returns:

the SDF pattern object of currently selected PatternColorSpace used for stroking.

GetTextRenderMode()

Return type:

int

Returns:

current text rendering mode.

The text rendering mode determines whether showing text causes glyph outlines to be stroked, filled, used as a clipping boundary, or some combination of the three. See Section 5.2.5 in PDF Reference Manual for details..

GetTextRise()

Return type:

double

Returns:

current value of text rise

Text rise specifies the distance, in unscaled text space units, to move the baseline up or down from its default location. Positive values of text rise move the baseline up

GetTransferFunct()

Return type:

Obj

Returns:

currently selected transfer function (NULL by default) used during color conversion process. A transfer function adjusts the values of color components to compensate for nonlinear response in an output device and in the human eye. Corresponds to the /TR key within the ExtGState’s dictionary.

GetTransform()

Return type:

Matrix2D

Returns:

the transformation matrix for this element.

Notes: If you are looking for a matrix that maps coordinates to the initial user space see Element::GetCTM().

GetUCRFunct()

Return type:

Obj

Returns:

currently selected undercolor-removal function (NULL by default) used during conversion between DeviceRGB and DeviceCMYK. Corresponds to the /UCR key within the ExtGState’s dictionary.

GetWordSpacing()

Return type:

double

Returns:

currently selected word spacing

Word spacing works the same way as character spacing, but applies only to the space character (char code 32). See Section 5.2.2 in PDF Reference Manual for details.

IsTextKnockout()

Return type:

boolean

Returns:

a boolean flag that determines the text element is considered elementary objects for purposes of color compositing in the transparent imaging model.

SetAISFlag(AIS)

Specifies if the alpha is to be interpreted as a shape or opacity mask. The alpha source flag (‘alpha is shape’), specifies whether the current soft mask and alphaant are to be interpreted as shape values (true) or opacity values (false).

Parameters:

AIS (boolean) – true for interpretation as shape values or false for opacity values

SetAutoStrokeAdjust(SA)

Specify whether to apply automatic stroke adjustment. Corresponds to the /SA key within the ExtGState’s dictionary.

Parameters:

SA (boolean) – if true automatic stroke adjustment will be applied.

SetBlackGenFunct(BG)

Sets black-generation function used during conversion between DeviceRGB and DeviceCMYK. Corresponds to the /BG key within the ExtGState’s dictionary.

Parameters:

BG (Obj) –

• SDF/Cos black-generation function or name

SetBlendMode(BM)

Sets the current blend mode to be used in the transparent imaging model. Corresponds to the /BM key within the ExtGState’s dictionary.

Parameters:

BM (int) –

• New blending mode type.

// C#
gs.SetBlendMode(GState.BlendMode.e_lighten);

// C++
gs-SetBlendMode(GState::e_lighten);

SetCharSpacing(char_spacing)

Sets character spacing.

Parameters:

char_spacing (double) – a number specified in unscaled text space units. When the glyph for each character in the string is rendered, the character spacing is added to the horizontal or vertical component of the glyph’s displacement, depending on the writing mode. See Section 5.2.1 in PDF Reference Manual for details.

SetDashPattern(dash_array, phase)

Sets the dash pattern used to stroke paths. The line dash pattern controls the pattern of dashes and gaps used to stroke paths. It is specified by a dash array and a dash phase. The elements of both the dash array and the dash phase are expressed in user space units.

Parameters:

• dash_array (std::vector< double,std::allocator< double > >) – the numbers that specify the lengths of alternating dashes and gaps.

• phase (double) – specifies the distance into the dash pattern at which to start the dash.

SetFillColor(args)

Overload 1:

Sets the color value/point used for filling operations.

Parameters:

c (ColorPt) – the color used for filling operations The color value must be represented in the currently selected color space used for filling.

Overload 2:

Set the fill color to the given tiling pattern.

Parameters:

pattern (PatternColor) – New pattern color.

Notes: The currently selected fill color space must be Pattern color space.

Overload 3:

Set the fill color to the given uncolored tiling pattern.

Parameters:

• pattern (PatternColor) – PatternColor (PatternType = 1 and PaintType = 2) object.

• c (ColorPt) – is a color in the pattern’s underlying color space.

Notes: The currently selected fill color space must be Pattern color space.

SetFillColorSpace(cs)

Sets the color space used for filling operations

Parameters:

cs (ColorSpace) – ColorSpace object to use for filling operations

SetFillOpacity(ca)

Sets the opacity value for painting operations other than stroking. Corresponds to the value of the /ca key in the ExtGState dictionary.

Parameters:

ca (double) – value to set fill opacity to

SetFillOverprint(op)

Specifies if overprint is enabled for fill operations. Corresponds to the /op key within the ExtGState’s dictionary.

Parameters:

op (boolean) – true to enable overprint for fill, false to disable.

SetFlatness(flatness)

Sets the value of flatness tolerance.

Parameters:

flatness (double) – is a number in the range 0 to 100; a value of 0 specifies the output device’s default flatness tolerance.

The flatness tolerance controls the maximum permitted distance in device pixels between the mathematically correct path and an approximationructed from straight line segments.

SetFont(font, font_sz)

Sets the font and font size used to draw text.

Parameters:

• font (Font) – Font to draw the text with

• font_sz (double) – size of the font to draw the text with

SetHalftone(HT)

Sets currently selected halftone dictionary or stream (NULL by default). Corresponds to the /HT key within the ExtGState’s dictionary. Halftoning is a process by which continuous-tone colors are approximated on an output device that can achieve only a limited number of discrete colors.

Parameters:

HT (Obj) –

• SDF/Cos halftone dictionary, stream, or name

SetHorizontalScale(hscale)

Sets horizontal scale. The horizontal scaling parameter adjusts the width of glyphs by stretching or compressing them in the horizontal direction. Its value is specified as a percentage of the normal width of the glyphs, with 100 being the normal width. The scaling always applies to the horizontal coordinate in text space, independently of the writing mode. See Section 5.2.3 in PDF Reference Manual for details.

Parameters:

hscale (double) – value to set horizontal scale to.

SetLeading(leading)

Sets the leading parameter.

The leading parameter is measured in unscaled text space units. It specifies the vertical distance between the baselines of adjacent lines of text. See Section 5.2.4 in PDF Reference Manual for details.

Parameters:

leading (double) – number representing vertical distance between lines of text

SetLineCap(cap)

Sets LineCap style property.

The line cap style specifies the shape to be used at the ends of open subpaths (and dashes, if any) when they are stroked.

SetLineJoin(join)

Sets LineJoin style property.

The line join style specifies the shape to be used at the corners of paths that are stroked.

SetLineWidth(width)

Sets the thickness of the line used to stroke a path.

Parameters:

width (double) – a non-negative number expressed in user space units. A line width of 0 denotes the thinnest line that can be rendered at device resolution: 1 device pixel wide.

SetMiterLimit(miter_limit)

Sets miter limit.

Parameters:

miter_limit (double) – A number that imposes a maximum on the ratio of the miter length to the line width. When the limit is exceeded, the join is converted from a miter to a bevel.

SetOverprintMode(OPM)

Sets the overprint mode. Corresponds to the /OPM key within the ExtGState’s dictionary.

Parameters:

OPM (int) – overprint mode.

SetRenderingIntent(intent)

Sets the color intent to be used for rendering the Element.

SetSmoothnessTolerance(SM)

Sets the smoothness tolerance used to control the quality of smooth shading. Corresponds to the /SM key within the ExtGState’s dictionary.

SetSoftMask(SM)

Sets the soft mask of the extended graphics state. Corresponds to the /SMask key within the ExtGState’s dictionary.

Parameters:

SM (Obj) –

• SDF/Cos black-generation function or name

SetStrokeColor(args)

Overload 1:

Sets the color value/point used for stroking operations.

Parameters:

c (ColorPt) – is the color used for stroking operations

Notes: The color value must be represented in the currently selected color space used for stroking.

Overload 2:

Set the stroke color to the given tiling pattern.

Parameters:

pattern (PatternColor) – SDF pattern object.

Notes: The currently selected stroke color space must be Pattern color space.

Overload 3:

Set the stroke color to the given uncolored tiling pattern.

Parameters:

• pattern (PatternColor) – pattern (PatternType = 1 and PaintType = 2) object.

• c (ColorPt) – is a color in the pattern’s underlying color space.

Notes: The currently selected stroke color space must be Pattern color space.

SetStrokeColorSpace(cs)

Sets the color space used for stroking operations

Parameters:

cs (ColorSpace) – ColorSpace object to use for stroking operations

SetStrokeOpacity(ca)

Sets opacity value for stroke painting operations for paths and glyph outlines. Corresponds to the value of the /CA key in the ExtGState dictionary.

Parameters:

ca (double) – value to set stroke opacity to

SetStrokeOverprint(OP)

Specifies if overprint is enabled for stroke operations. Corresponds to the /OP key within the ExtGState’s dictionary.

Parameters:

OP (boolean) – true to enable overprint for stroke, false to disable.

SetTextKnockout(knockout)

Mark the object as elementary for purposes of color compositing in the transparent imaging model.

Parameters:

knockout (boolean) – Whether an object is elementary or not.

SetTextRenderMode(rmode)

Sets text rendering mode. The text rendering mode determines whether showing text causes glyph outlines to be stroked, filled, used as a clipping boundary, or some combination of the three. See Section 5.2.5 in PDF Reference Manual for details..

SetTextRise(rise)

Sets text rise. Text rise specifies the distance, in unscaled text space units, to move the baseline up or down from its default location. Positive values of text rise move the baseline up

Parameters:

rise (double) – distance to move baseline up. Negative values move baseline down.

SetTransferFunct(TR)

Sets transfer function used during color conversion process. A transfer function adjusts the values of color components to compensate for nonlinear response in an output device and in the human eye. Corresponds to the /TR key within the ExtGState’s dictionary.

Parameters:

TR (Obj) –

• SDF/Cos transfer function, array, or name

SetTransform(args)

Overload 1:

Set the transformation matrix associated with this element.

Parameters:

mtx (Matrix2D) – The new transformation for this text element.

Notes: in PDF associating a transformation matrix with an element (‘cm’ operator) will also affect all subsequent elements.

Overload 2:

Set the transformation matrix associated with this element.

A transformation matrix in PDF is specified by six numbers, usually in the form of an array containing six elements. In its most general form, this array is denoted [a b c d h v]; it can represent any linear transformation from one coordinate system to another. For more information about PDF matrices please refer to section 4.2.2 ‘Common Transformations’ in PDF Reference Manual, and to documentation for Common::Matrix2D class.

Parameters:

• a (double) –

  • horizontal ‘scaling’ component of the new text matrix.

• b (double) –

  • ‘rotation’ component of the new text matrix.

• c (double) –

  • ‘rotation’ component of the new text matrix.

• d (double) –

  • vertical ‘scaling’ component of the new text matrix.

• h (double) –

  • horizontal translation component of the new text matrix.

• v (double) –

  • vertical translation component of the new text matrix.

SetUCRFunct(UCR)

Sets undercolor-removal function used during conversion between DeviceRGB and DeviceCMYK. Corresponds to the /UCR key within the ExtGState’s dictionary.

Parameters:

UCR (Obj) –

• SDF/Cos undercolor-removal function or name

SetWordSpacing(word_spacing)

Sets word spacing.

Parameters:

word_spacing (double) –

• a number specified in unscaled text space units.

Word spacing works the same way as character spacing, but applies only to the space character (char code 32). See Section 5.2.2 in PDF Reference Manual for details.

e_BG_funct = 33

e_UCR_funct = 34

e_absolute_colorimetric = 0

e_alpha_is_shape = 25

e_auto_stoke_adjust = 28

e_bevel_join = 2

e_bl_color = 16

e_bl_color_burn = 8

e_bl_color_dodge = 7

e_bl_compatible = 0

e_bl_darken = 5

e_bl_difference = 4

e_bl_exclusion = 9

e_bl_hard_light = 10

e_bl_hue = 14

e_bl_lighten = 6

e_bl_luminosity = 13

e_bl_multiply = 2

e_bl_normal = 1

e_bl_overlay = 11

e_bl_saturation = 15

e_bl_screen = 3

e_bl_soft_light = 12

e_blend_mode = 22

e_butt_cap = 0

e_char_spacing = 12

e_clip_text = 7

e_dash_pattern = 11

e_fill_clip_text = 4

e_fill_color = 5

e_fill_cs = 4

e_fill_overprint = 30

e_fill_stroke_clip_text = 6

e_fill_stroke_text = 2

e_fill_text = 0

e_flatness = 9

e_font = 16

e_font_size = 17

e_halftone = 35

e_horizontal_scale = 14

e_invisible_text = 3

e_leading = 15

e_line_cap = 7

e_line_join = 8

e_line_width = 6

e_miter_join = 0

e_miter_limit = 10

e_null = 36

e_opacity_fill = 23

e_opacity_stroke = 24

e_overprint_mode = 31

e_perceptual = 3

e_relative_colorimetric = 1

e_rendering_intent = 1

e_round_cap = 1

e_round_join = 1

e_saturation = 2

e_smoothnes = 27

e_soft_mask = 26

e_square_cap = 2

e_stroke_clip_text = 5

e_stroke_color = 3

e_stroke_cs = 2

e_stroke_overprint = 29

e_stroke_text = 1

e_text_knockout = 20

e_text_pos_offset = 21

e_text_render_mode = 18

e_text_rise = 19

e_transfer_funct = 32

e_transform = 0

e_word_spacing = 13

property mp_state

property thisown

The membership flag

apryse_sdk.GState_GetRenderingIntentType(name)

A utility function that maps a string representing a rendering intent to RenderingIntent type.

Parameters:

name (string) – string that represents the rendering intent to get.

Return type:

int

Returns:

The color rendering intent type matching the specified string

class apryse_sdk.Group(args)

Bases: object

The OCG::Group object represents an optional-content group. This corresponds to a PDF OCG dictionary representing a collection of graphic objects that can be made visible or invisible (Section 4.10.1 ‘Optional Content Groups’ in PDF Reference). Any graphic content of the PDF can be made optional, including page contents, XObjects, and annotations. The specific content objects in the group have an OC entry in the PDF as part of the surrounding marked content or in the XObject dictionary. The group itself is a named object that can be typically manipulated through a Layers panel in a PDF viewer.

In the simplest case, the group’s ON-OFF state makes the associated content visible or hidden. The ON-OFF state of a group can be toggled for a particular context (OCG::Context), and a set of states is kept in a configuration (OCG::Config). The visibility can depend on more than one group in an optional-content membership dictionary (OCG::OCMD), and can also be affected by the context’s draw mode (OCGContext::OCDrawMode).

A group has an Intent entry, broadly describing the intended use. A group’s content is considered to be optional (that is, the group’s state is considered in its visibility) if any intent in its list matches an intent of the context. The intent list of the context is usually set from the intent list of the document configuration.

A Usage dictionary entry provides more specific intended usage information than an intent entry. Possible key values are: CreatorInfo, Language, Export, Zoom, Print, View, User, PageElement. The usage value can act as a kind of metadata, describing the sort of things that belong to the group, such as text in French, fine detail on a map, or a watermark. The usage values can also be used by the AutoState mechanism to make decisions about what groups should be on and what groups should be off. The AutoState mechanism considers the usage information in the OCGs, the AS array of the configuration, and external factors; for example, the language the application is running in, the current zoom level on the page, or whether the page is being printed.

static Create(doc, name)

Creates a new optional-content group (OCG) object in the document.

Parameters:

• doc (PDFDoc) – The document in which the new OCG will be created.

• name (string) – The name of the optional-content group.

Return type:

Group

Returns:

The newly created OCG::Group object.

GetCurrentState(context)

Return type:

boolean

Returns:

true if this OCG object is in the ON state in a given context, false otherwise.

Parameters:

context (Context) – The context for which to get the group’s state.

GetInitialState(config)

Return type:

boolean

Returns:

The initial state (ON or OFF) of the optional-content group (OCG) object in a given configuration.

Parameters:

config (Config) – The configuration for which to get the group’s initial state.

Notes: If the configuration has a BaseState of Unchanged, and the OCG is not listed explicitly in its ON list or OFF list, then the initial state is taken from the OCG’s current state in the document’s default context.

GetIntent()

Return type:

Obj

Returns:

OCG intent. An intent is a name object (or an array of name objects) broadly describing the intended use, which can be either “View” or “Design”. A group’s content is considered to be optional (that is, the group’s state is considered in its visibility) if any intent in its list matches an intent of the context. The intent list of the context is usually set from the intent list of the document configuration.

GetName()

Return type:

string

Returns:

the name of this optional-content group (OCG).

GetSDFObj()

Return type:

Obj

Returns:

Pointer to the underlying SDF/Cos object.

GetUsage(key)

Return type:

Obj

Returns:

The usage information associated with the given key in the Usage dictionary for the group, or a NULL if the entry is not present. A Usage dictionary entry provides more specific intended usage information than an intent entry.

Parameters:

key (string) – The usage key in the usage dictionary entry. The possible key values are: CreatorInfo, Language, Export, Zoom, Print, View, User, PageElement.

HasUsage()

Return type:

boolean

Returns:

true if this group is associated with a Usage dictionary, false otherwise.

IsLocked(config)

Return type:

boolean

Returns:

true if this OCG is locked in a given configuration, false otherwise. The on/off state of a locked OCG cannot be toggled by the user through the user interface.

Parameters:

config (Config) – The OC configuration.

IsValid()

Return type:

boolean

Returns:

True if this is a valid (non-null) OCG, false otherwise.

SetCurrentState(context, state)

Sets the current ON-OFF state of the optional-content group (OCG) object in a given context.

Parameters:

• context (Context) – The context for which to set the group’s state.

• state (boolean) – The new state.

SetInitialState(config, state)

Sets the initial state (ON or OFF) of the optional-content group (OCG) object in a given configuration.

Parameters:

• config (Config) – The configuration for which to set the group’s initial state.

• state (boolean) – The new initial state, true if the state is ON, false if it is OFF.

SetIntent(intent)

Sets the Intent entry in an optional-content group’s SDF/Cos dictionary. For more information, see GetIntent().

Parameters:

intent (Obj) – The new Intent entry value (a name object or an array of name objects).

SetLocked(config, locked)

Sets the locked state of an OCG in a given configuration. The on/off state of a locked OCG cannot be toggled by the user through the user interface.

Parameters:

• config (Config) – IN/OUT The optional-content configuration.

• locked (boolean) – true if the OCG should be locked, false otherwise.

SetName(name)

Sets the name of this optional-content group (OCG).

Parameters:

name (string) – The new name.

property mp_obj

property thisown

The membership flag

apryse_sdk.Group_Create(doc, name)

Creates a new optional-content group (OCG) object in the document.

Parameters:

• doc (PDFDoc) – The document in which the new OCG will be created.

• name (string) – The name of the optional-content group.

Return type:

Group

Returns:

The newly created OCG::Group object.

class apryse_sdk.HTML2PDF

Bases: object

‘pdftron.PDF.HTML2PDF’ is an optional PDFNet Add-On utility class that can be used to convert HTML web pages into PDF documents by using an external module (html2pdf).

The html2pdf modules can be downloaded from http: www.pdftron.com/pdfnet/downloads.html.

Users can convert HTML pages to PDF using the following operations: - Simple one line static method to convert a single web page to PDF. - Convert HTML pages from URL or string, plus optional table of contents, in user defined order. - Optionally configure settings for proxy, images, java script, and more for each HTML page. - Optionally configure the PDF output, including page size, margins, orientation, and more. - Optionally add table of contents, including setting the depth and appearance.

The following code converts a single webpage to pdf

using namespace pdftron;
using namespace PDF;

PDFDoc pdfdoc;
if ( HTML2PDF::Convert(pdfdoc, "http://www.gutenberg.org/wiki/Main_Page") )
                pdfdoc.Save(outputFile, SDF::SDFDoc::e_remove_unused, NULL);

The following code demonstrates how to convert multiple web pages into one pdf, excluding the background, and with lowered image quality to save space.

using namespace pdftron;
using namespace PDF;

HTML2PDF converter;
converter.SetImageQuality(25);

HTML2PDF::WebPageSettings settings;
settings.SetPrintBackground(false);

converter.InsertFromURL("http://www.gutenberg.org/wiki/Main_Page", settings);

PDFDoc pdfdoc;
if ( converter.Convert(pdfdoc) )
                pdfdoc.Save(outputFile, SDF::SDFDoc::e_remove_unused, NULL);

AddCookie(name, value)

Add cookie to the HTTP Headers when converting via a URL.

Parameters:

• name (string) –

  • the name of the cookie.

• value (string) –

  • the value of the cookie.

Convert(doc)

Convert HTML documents and append the results to doc.

Return type:

boolean

Returns:

true if successful, otherwise false. Use ‘GetHttpErrorCode’ for possible HTTP errors.

Parameters:

doc (PDFDoc) –

• Target PDF to which converted HTML pages will

be appended to.

Notes: Use ‘InsertFromURL’ and ‘InsertFromHtmlString’ to add HTML documents to be converted.

Destroy()

Frees the native memory of the object.

DumpOutline(xml_file)

Save outline to a xml file.

Parameters:

xml_file (string) –

• Path of where xml data representing outline

of produced PDF should be saved to.

Notes: This option is deprecated in the latest HTML2PDF module and may have no effect.

GetHTTPErrorCode()

Return the largest HTTP error code encountered during conversion

Return type:

int

Returns:

the largest HTTP code greater then or equal to 300 encountered during loading of any of the supplied objects, if no such error code is found 0 is returned.

Notes: This function will only return a useful result after ‘Convert’ has been called.

GetLog()

Get results of conversion, including errors and warnings, in human readable form.

Return type:

string

Returns:

String containing results of conversion.

InsertFromHtmlString(args)

Overload 1:

Convert HTML encoded in string.

Parameters:

html (string) –

• String containing HTML code.

Overload 2:

Convert HTML encoded in string.

Parameters:

• html (string) –

  • String containing HTML code.

• settings (WebPageSettings) –

  • How the HTML content described in html is loaded.

InsertFromURL(args)

Overload 1:

Add a web page to be converted. A single URL typically results in many PDF pages.

Parameters:

url (string) –

• HTML page, or relative path to local HTML page

Overload 2:

Add a web page to be converted. A single URL typically results in many PDF pages.

Parameters:

• url (string) –

  • HTML page, or relative path to local HTML page

• settings (WebPageSettings) –

  • How the web page should be loaded and converted

InsertTOC(args)

Overload 1:

Add a table of contents to the produced PDF. Notes: This option is deprecated in the latest HTML2PDF module and may have no effect.

Overload 2:

Add a table of contents to the produced PDF.

Parameters:

settings (TOCSettings) –

• Settings for the table of contents.

Notes: This option is deprecated in the latest HTML2PDF module and may have no effect.

static IsModuleAvailable()

Find out whether the HTLML2PDF module is available (and licensed).

Return type:

boolean

Returns:

returns true if HTLML2PDF operations can be performed.

SetCompatibilityMode(compatibility)

Provides the ability to run HTML to PDF conversion to run in compatibility mode, which runs with altered graphics options and does not create a dedicated render process. This option may be somewhat slower than the default mode. However, it may be required on environments with limited platform dependencies, such as AWS Lambda.

Parameters:

compatibility (boolean) –

• If true, compatibility mode is enabled.

SetCookieJar(path)

Path of file used for loading and storing cookies.

Parameters:

path (string) –

• Path to file used for loading and storing cookies.

Notes: This option is deprecated in the latest HTML2PDF module and may have no effect.

SetCustomHeader(name, value)

Add a custom HTTP header specified by name and value.

Parameters:

• name (string) –

  • the name of the custom header.

• value (string) –

  • the value of the custom header.

SetDPI(dpi)

Change the DPI explicitly for the output PDF.

Parameters:

dpi (int) –

• Dots per inch, e.g. 80.

This has no effect on X11 based systems. Notes: Results also depend on ‘SetSmartShrinking’.

SetFooter(footer)

Set footer of generated PDF.

Parameters:

footer (string) – HTML string to be used as the footer

SetHeader(header)

Set header of generated PDF.

Parameters:

header (string) – HTML string to be used as the header

SetImageDPI(dpi)

Maximum DPI to use for images in the generated PDF.

Parameters:

dpi (int) –

• Maximum dpi of images in produced PDF, e.g. 80.

SetImageQuality(quality)

JPEG compression factor to use when generating PDF.

Parameters:

quality (int) –

• Compression factor, e.g. 92.

Notes: This option is deprecated in the latest HTML2PDF module and may have no effect.

SetLandscape(enable)

Set page orientation for output PDF.

Parameters:

enable (boolean) –

• If true generated PDF pages will be orientated to

landscape, otherwise orientation will be portrait.

SetLogFilePath(path)

Sets the location of the log file to be used during conversion.

Parameters:

path (string) – Full path and filename of file to log to.

SetMargins(top, bottom, left, right)

Set margins of generated PDF.

Parameters:

• top (string) –

  • Size of the top margin, e.g. “2cm”.

• bottom (string) –

  • Size of the bottom margin, e.g. “2cm”.

• left (string) –

  • Size of the left margin, e.g. “2cm”.

• right (string) –

  • Size of the right margin, e.g. “2cm”.

Notes: Supported units are mm, cm, m, in, pc(pica), px(pixel) and pt(point).

static SetModulePath(path)

Set the only location that PDFNet will look for the html2pdf module.

Parameters:

path (string) –

• A folder or file path. If non-empty, PDFNet will only

look in path for the html2pdf module, otherwise it will search in the default locations for the module.

SetOutline(enable, depth=4)

Add bookmarks to the PDF.

Parameters:

• enable (boolean) –

  • If true bookmarks will be generated for the

  produced PDF.

• depth (int) –

  • Maximum depth of the outline (e.g. 4).

Notes: This option is deprecated in the latest HTML2PDF module and may have no effect.

SetPDFCompression(enable)

Use loss less compression to create PDF.

Parameters:

enable (boolean) –

• If true loss less compression will be used to

create PDF

Notes: This option is deprecated in the latest HTML2PDF module and may have no effect.

SetPaperSize(args)

Overload 1:

Set paper size of output PDF

Parameters:

size (int) –

• Paper size to use for produced PDF.

Overload 2:

Manually set the paper dimensions of the produced PDF.

Parameters:

• width (string) –

  • Width of the page, e.g. “4cm”.

• height (string) –

  • Height of the page, eg. “12in”.

Notes: Supported units are mm, cm, m, in, pc(pica), px(pixel) and pt(point).

SetQuiet(quiet)

Display HTML to PDF conversion progress, warnings, and errors, to stdout.

Parameters:

quiet (boolean) –

• If false, progress information is sent to stdout during conversion.

Notes: You can get the final results using GetLog.

property mp_html2pdf

property thisown

The membership flag

apryse_sdk.HTML2PDF_IsModuleAvailable()

Find out whether the HTLML2PDF module is available (and licensed).

Return type:

boolean

Returns:

returns true if HTLML2PDF operations can be performed.

apryse_sdk.HTML2PDF_SetModulePath(path)

Set the only location that PDFNet will look for the html2pdf module.

Parameters:

path (string) –

• A folder or file path. If non-empty, PDFNet will only

look in path for the html2pdf module, otherwise it will search in the default locations for the module.

class apryse_sdk.HTMLOutputOptions

Bases: object

A class containing options common to ToHtml and ToEpub functions

SetConnectHyphens(connect)

Specifies whether hyphens in the PDF should be connected. Default is false. Notes: This option is only available for e_reflow_paragraphs and e_reflow_full modes.

Parameters:

connect (boolean) – if true, hyphens in the PDF will be connected.

SetContentReflowSetting(reflow)

Switch between fixed (pre-paginated) and reflowable HTML generation. Default is e_fixed_position. In e_reflow_paragraphs mode (now deprecated), conversions require that the optional PDFTron HTML reflow paragraphs add-on module is available. In e_reflow_full mode, conversions require that the optional PDFTron StructuredOutput add-on module is available.

Parameters:

reflow (int) – the generated HTML will be either fixed or reflowable.

See also: ContentReflowSetting See also: StructuredOutputModule See also: PDF2HtmlReflowParagraphsModule

SetDPI(dpi)

The output resolution, from 1 to 1000, in Dots Per Inch (DPI) at which to render elements which cannot be directly converted. Default is 140. Notes: This option is only available for e_fixed_position mode.

Parameters:

dpi (int) – the resolution in Dots Per Inch

SetDisableVerticalSplit(disable)

Specifies whether to disable the detection of section columns. Default is false. Enable this if your tables are coming out as section columns. Notes: This option is only available for e_reflow_paragraphs mode. In e_reflow_full mode, columns are detected automatically.

Parameters:

disable (boolean) – if true, the detection of section columns are disabled.

SetEmbedImages(embed)

Specifies whether images are embedded in the HTML without having to link to external files. Default is true. Notes: This option is only available for e_reflow_paragraphs and e_reflow_full modes.

Parameters:

embed (boolean) – if true, images are embedd in the HTML, otherwise, images are saved as external files.

SetExternalLinks(enable)

Enable the conversion of external URL navigation. Default is false.

Parameters:

enable (boolean) – if true, links that specify external URL’s are converted into HTML.

Notes: This option is only available for e_fixed_position mode.

SetFileConversionTimeoutSeconds(seconds)

Specifies the amount of time in seconds after which the conversion fails. Default is 300. Very long files need more time to convert. Notes: This option is only available for e_reflow_paragraphs mode. The timeout feature is not necessary in other modes.

Parameters:

seconds (int) – the timeout in seconds.

SetImageDPI(dpi)

Specifies the output image resolution, from 8 to 600, in Pixels Per Inch (PPI). The higher the PPI, the larger the image. Default is 192. Notes: This option is only available for e_reflow_paragraphs mode. In other modes, image resolution is determined automatically for an optimal result.

Parameters:

dpi (int) – the resolution in Pixels Per Inch.

SetInternalLinks(enable)

Enable the conversion of internal document navigation. Default is false.

Parameters:

enable (boolean) – if true, links that specify page jumps are converted into HTML.

Notes: This option is only available for e_fixed_position mode.

SetJPGQuality(quality)

Specifies the compression quality to use when generating JPEG images. Notes: This option is only available for e_fixed_position and e_reflow_paragraphs modes. In e_reflow_full mode, the optimal JPEG quality is chosen automatically for best balance between size and quality.

Parameters:

quality (int) – the JPEG compression quality, from 0 (highest compression) to 100 (best quality).

SetLanguage(language)

Specifies the OCR language. Default is automatic language detection. Notes: This option is only available for e_reflow_full mode.

Parameters:

language (int) – the OCR language.

SetMaximumImagePixels(max_pixels)

Specifies the maximum image slice size in pixels. Default is 2000000. Notes: This setting now will no longer reduce the total number of image pixels. Instead a lower value will just produce more slices and vice versa. Since image compression works better with more pixels a larger max pixels should generally create smaller files. This option is only available for e_fixed_position mode.

Parameters:

max_pixels (int) – the maximum number of pixels an image can have

SetNoPageWidth(enable)

Determines whether to flow contents across the entire browser window. Default is false. Notes: This option is only available for e_reflow_paragraphs mode. In e_reflow_full mode, content always flows across the entire browser window.

Parameters:

enable (boolean) – if true, content will flow across entire page.

SetPDFPassword(password)

Specifies the password if the PDF requires one. Notes: This option is only available for e_reflow_paragraphs and e_reflow_full modes.

Parameters:

password (string) – the PDF password, if required; an empty string otherwise.

SetPages(page_from, page_to)

Specifies a range of pages to be converted. By default all pages are converted. The first page has the page number of 1. Notes: This option is only available for e_reflow_paragraphs and e_reflow_full modes.

Parameters:

• page_from (int) – the first page to be converted.

• page_to (int) – the last page to be converted (inclusive). Use a negative value to specify the last page in the PDF.

SetPreferJPG(prefer_jpg)

Use JPG files rather than PNG. This will apply to all generated images. Default is true. Notes: This option is only available for e_fixed_position and e_reflow_paragraphs modes.

Parameters:

prefer_jpg (boolean) – if true JPG images will be used whenever possible.

SetReportFile(path)

Generate a XML file that contains additional information about the conversion process. By default no report is generated.

Parameters:

path (string) – the file path to which the XML report is written to.

Notes: This option is only available for e_fixed_position mode.

SetScale(scale)

Set an overall scaling of the generated HTML pages. Default is 1.0.

Parameters:

scale (double) – A number greater than 0 which is used as a scale factor. For example, calling SetScale(0.5) will reduce the HTML body of the page to half its original size, whereas SetScale(2) will double the HTML body dimensions of the page and will rescale all page content appropriately.

Notes: This option is only available for e_fixed_position mode.

SetSearchableImageSetting(setting)

Specifies how scanned image pages should be converted. Default is e_ocr_image_text. Notes: This option is only available for e_reflow_paragraphs and e_reflow_full modes.

Parameters:

setting (int) – the searchable image setting.

Remarks: In e_reflow_paragraphs mode, this feature does not perform OCR, but instead it relies on pre-existing text from previous OCR. Both images and pre-existing hidden text are kept by default. In e_reflow_full mode, pre-existing OCRed content is ignored and a new OCR is performed from scratch by default. e_ocr_off can be used to disable OCR. See also: SearchableImageSetting

SetSimpleLists(enable)

Determines whether to use tags for list items. Default is false. Notes: This option is only available for e_reflow_paragraphs mode. In e_reflow_full mode, list items always use tags.

Parameters:

enable (boolean) – if true, tags are used for list items.

SetSimplifyText(enable)

Controls whether converter optimizes DOM or preserves text placement accuracy. Default is false.

Parameters:

enable (boolean) – if true, converter will try to reduce DOM complexity at the expense of text placement accuracy.

Notes: This option is only available for e_fixed_position mode.

SetTitle(title)

Specifies the title for the output HTML. Notes: This option is only available for e_reflow_paragraphs mode. HTML titles are not supported in other modes at the moment.

Parameters:

title (string) – the title of the output HTML.

e_fixed_position = 0

e_ocr_always = 4

e_ocr_image = 1

e_ocr_image_text = 0

e_ocr_off = 3

e_ocr_text = 2

e_reflow_full = 2

e_reflow_paragraphs = 1

property thisown

The membership flag

class apryse_sdk.Highlight(args)

Bases: object

property length

property page_num

property position

property thisown

The membership flag

class apryse_sdk.HighlightAnnot(args)

Bases: TextMarkup

A Highlight annotation covers a word or a group of contiguous words with partially transparent color.

static Create(doc, pos)

Creates a new Highlight annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the Highlight annotation is added.

• pos (Rect) – A rectangle specifying the Highlight annotation’s bounds in default user space units.

Return type:

HighlightAnnot

Returns:

A newly created blank Highlight annotation.

static CreateAnnot(doc, pos)

property thisown

The membership flag

apryse_sdk.HighlightAnnot_Create(doc, pos)

Creates a new Highlight annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the Highlight annotation is added.

• pos (Rect) – A rectangle specifying the Highlight annotation’s bounds in default user space units.

Return type:

HighlightAnnot

Returns:

A newly created blank Highlight annotation.

apryse_sdk.HighlightAnnot_CreateAnnot(doc, pos)

class apryse_sdk.Highlights(args)

Bases: object

Highlights is used to store the necessary information and perform certain tasks in accordance with Adobe’s Highlight standard, whose details can be found at:

http://partners.adobe.com/public/developer/en/pdf/HighlightFileFormat.pdf

In a nutshell, the Highlights class maintains a set of highlights. Each highlight contains three pieces of information:

page: the number of the page this Highlight is on; position: the start position (text offset) of this Highlight; length: the length of this Highlight.

Possible use case scenarios for Highlights include:

• Load a Highlight file (in XML format) and highlight the corresponding texts in the viewer (e.g., if the viewer is implemented using PDFViewCtrl, it can be achieved simply by calling PDFViewCtrl::SelectByHighlights() method);

• Save the Highlight information (e.g.,ructed by the TextSearch class) to an XML file for external uses.

Note

• The Highlights class does not maintain the corresponding PDF document for its highlights. It is the user’s responsibility to match them up.

• The Highlights class ensures that each highlight it maintains is unique (no two highlights have the same page, position and length values).

• The current implementation of Highlights only supports the ‘characters’ encoding for ‘units’ as described in the format; the ‘words’ encoding is not supported at this point.

For a sample code, please take a look at the TextSearchTest sample project.

Add(hlts)

Add highlights.

Parameters:

hlts (Highlights) – the Highlights instance containing the highlights to be added.

Begin(doc)

Rewind the internal pointer to the first highlight.

Parameters:

doc (PDFDoc) – the PDF document to which the highlights correspond.

Notes: the PDF document can be a dummy document unless GetCurrentQuads() is to be called.

Clear()

Clear the current Highlight information in the class.

static CreateInternal(impl)

Destroy()

Frees the native memory of the object.

GetCurrentPageNumber()

Get the page number of the current highlight.

GetCurrentQuads()

Get the corresponding quadrangles of the current highlight.

Parameters:

quads – the output pointer to the resulting quadrangles.

Return type:

std::vector< PDF::QuadPoint,std::allocator< PDF::QuadPoint > >

Returns:

the number of the resulting quadrangles. Each quadrangle has eight doubles (x1, y1), (x2, y2), (x3, y3), (x4, y4) denoting the four vertices in counter-clockwise order.

Notes: the ‘quads’ array is owned by the current Highlights and does not need to be explicitly released. Since a highlight may correspond to multiple quadrangles, e.g., when it crosses a line, the number of resulting quadrangles may be larger than 1.

GetCurrentTextRange()

Get a TextRange object that represents the current highlight.

GetHandleInternal()

HasNext()

Query if there is any subsequent highlight after the current highlight.

Load(file_name)

Load the Highlight information from a file. Note that the pre-existing Highlight information is discarded.

Parameters:

file_name (string) – the name of the file to load from.

Next()

Move the current highlight to the next highlight.

Save(file_name)

Save the current Highlight information in the class to a file.

Parameters:

file_name (string) – the name of the file to save to.

SaveToString()

Save the current Highlight information in the class to an XML string.

Return type:

string

Returns:

the highlight XML file contents as a string

property mp_highlights

property thisown

The membership flag

apryse_sdk.Highlights_CreateInternal(impl)

class apryse_sdk.Image(args)

Bases: object

Image class provides common methods for working with PDF images.

Notes: PDF::Element contains a similar interface used to access image data. To create the Image object from image PDF::Element, pass the Element’s SDF/Cos dictionary to Imageructor (i.e. Image image(element->GetXObject()) )

static Create(args)

Overload 1:

Create and embed an Image from an external file taking into account specified compression hints.

By default the function will either pass-through data preserving the original compression or will compress data using Flate compression. It is possible to fine tune compression or to select a different compression algorithm using ‘encoder_hints’ object.

Parameters:

• doc (SDFDoc) –

  • A document to which the image should be added. To obtain

  SDF::Doc from PDFDoc use PDFDoc::GetSDFDoc() or Obj::GetDoc().

• filename (string) –

  • The name of the image file. Currently supported formats are

  JPEG, PNG, GIF, TIFF, BMP, EMF, and WMF. Other raster formats can be embedded by decompressing image data and using other versions of Image::Create(…) method.

• encoder_hints (Obj) –

  • An optional SDF::Obj containing a hint (or an SDF::Array of

    hints) that could be used to select a specific compression method and compression parameters. For a concrete example of how to create encoder hints, please take a look at JBIG2Test and AddImage sample projects. The image encoder accepts the following hints:

  • /JBIG2; SDF::Name(“JBIG2”), An SDF::Name Object with value equal to “JBIG2”. If the

    image is monochrome (i.e. bpc == 1), the encoder will compress the image using JBIG2Decode filter. Note that JBIG2 compression is not recommended for use on scanned text/financial documents or equivalent

  since its lossless nature can lead to similar looking numbers or characters being replaced.

  • [/JBIG2 /Threshold 0.6 /SharePages 50] - Compress a monochrome image using lossy JBIG2Decode

  compression with the given image threshold and by sharing segments from a specified number of pages. The threshold is a doubleing point number in the range from 0.4 to 0.9. Increasing the threshold value will increase image quality, but may increase the file size. The default value for threshold is 0.85. “SharePages” parameter can be used to specify the maximum number of pages sharing a common ‘JBIG2Globals’ segment stream. Increasing the value of this parameter improves compression ratio at the expense of memory usage.

  • [/CCITT] - Compress a monochrome (i.e. bpc == 1) image using CCITT Group 4 compression. This algorithm typically produces

    larger output than JBIG2, but is lossless. This makes it much more suitable for scanned text documents. CCITT is the best option for more general monochrome compression use cases, since JBIG2 has potential to change image content.

  • [/JPEG] - Use JPEG compression with default compression.

  • [/JPEG /Quality 60] - Use JPEG compression with given quality setting. The “Quality”

    value is expressed on the 0..100 scale.

  • [/JPEG2000] - Use JPEG2000 compression to compress a RGB or a grayscale image.<para>

  • [/JP2] - Use JPEG2000 compression with JP2 encoding. JP2 does not support CMYK images.<para>

  • [/Flate] - Use Flate compression with maximum compression at the expense of

    speed.

  • [/Flate /Level 9] - Use Flate compression using specified compression level.

    Compression “Level” must be a number between 0 and 9: 1 gives best speed, 9 gives best compression, 0 gives no compression at all (the input data is simply copied a block at a time).

  • /RAW or [/RAW] - The encoder will not use any compression method and the image

    will be stored in the raw format.

Return type:

Image

Returns:

PDF::Image object representing the embedded image.

Notes: For C++ developers: Current document does not take the ownership of the encoder_hints object. Therefore it is a good programming practice to create encoder_hints object on the stack.

Overload 2:

Create and embed an Image. Embed the raw image data taking into account specified compression hints.

By default the function will compress all images using Flate compression. It is possible to fine tune compression or to select a different compression algorithm using ‘encoder_hints’ object.

Parameters:

• doc (SDFDoc) –

  • A document to which the image should be added. The ‘Doc’ object

  can be obtained using Obj::GetDoc() or PDFDoc::GetSDFDoc().

• buf (unsigned char) –

  • The stream or buffer containing image data. The image data must

  not be compressed and must follow PDF format for sample representation (please refer to section 4.8.2 ‘Sample Representation’ in PDF Reference Manual for details).

• width (int) –

  • The width of the image, in samples.

• height (int) –

  • The height of the image, in samples.

• bpc (int) –

  • The number of bits used to represent each color component.

• color_space (ColorSpace) –

  • The color space in which image samples are represented.

• encoder_hints (Obj) –

  • An optional parameter that can be used to fine tune

  compression or to select a different compression algorithm. See Image::Create() for details.

Return type:

Image

Returns:

PDF::Image object representing the embedded image.

Overload 3:

Create and embed an Image. Embed the raw image data taking into account specified compression hints.

By default the function will compress all images using Flate compression. It is possible to fine tune compression or to select a different compression algorithm using ‘encoder_hints’ object.

Parameters:

• doc (SDFDoc) –

  • A document to which the image should be added. The ‘Doc’ object

  can be obtained using Obj::GetDoc() or PDFDoc::GetSDFDoc().

• buf (unsigned char) –

  • The stream or buffer containing image data. The image data must

  not be compressed and must follow PDF format for sample representation (please refer to section 4.8.2 ‘Sample Representation’ in PDF Reference Manual for details).

• width (int) –

  • The width of the image, in samples.

• height (int) –

  • The height of the image, in samples.

• bpc (int) –

  • The number of bits used to represent each color component.

• color_space (ColorSpace) –

  • The color space in which image samples are represented.

• encoder_hints –

  • An optional parameter that can be used to fine tune

  compression or to select a different compression algorithm. See Image::Create() for details.

Return type:

Image

Returns:

PDF::Image object representing the embedded image.

Overload 4:

Create and embed an Image. Embed the raw image data taking into account specified compression hints. Notes: see Image::Create for details.

Overload 5:

Create and embed an Image. Embed the raw image data taking into account specified compression hints. Notes: see Image::Create for details.

Overload 6:

Create and embed an Image. Embed the raw image data taking into account specified compression hints. Notes: see Image::Create for details.

Overload 7:

Create and embed an Image. Embed the raw image data taking into account specified compression hints. Notes: see Image::Create for details.

Overload 8:

Create and embed an Image. Embed the raw image data taking into account specified compression hints.

Notes: see Image::Create for details. PDFNet takes ownership of the filter

Overload 9:

Create and embed an Image. Embed the raw image data taking into account specified compression hints.

Notes: see Image::Create for details. PDFNet takes ownership of the filter

Overload 10:

Directly embed the image that is already compressed using the Image::InputFilter format. The function can be used to pass-through pre-compressed image data.

Parameters:

• doc (SDFDoc) –

  • A document to which the image should be added. The ‘Doc’ object

  can be obtained using Obj::GetDoc() or PDFDoc::GetSDFDoc().

• buf (string) –

  • The stream or buffer containing compressed image data.

  The compression format must match the input_format parameter.

• width (int) –

  • The width of the image, in samples.

• height (int) –

  • The height of the image, in samples.

• bpc (int) –

  • The number of bits used to represent each color component.

• color_space (ColorSpace) –

  • The color space in which image samples are specified.

• input_format (int) –

  • Image::InputFilter describing the format of pre-compressed

  image data.

Return type:

Image

Returns:

PDF::Image object representing the embedded image.

Overload 11:

Embed the raw image data taking into account specified compression hints. Notes: see the above method for details.

static CreateImageMask(args)

Overload 1:

Create and embed an Image from any GDI+ Bitmap taking into account specified compression hints.

Notes: see Image::Create for details. This method is available only on Windows platforms.

Parameters:

• doc (SDFDoc) –

  • A document to which the image should be added. The ‘Doc’ object

  can be obtained using Obj::GetDoc() or PDFDoc::GetSDFDoc().

• bmp –

  • GDI+ bitmap.

Return type:

Image

Returns:

PDF::Image object representing the embedded image.

Create and embed an ImageMask. Embed the raw image data taking into account specified compression hints. The ImageMask can be used as a stencil mask for painting in the current color or as an explicit mask specifying which areas of the image to paint and which to mask out. One of the most important uses of stencil masking is for painting character glyphs represented as bitmaps.

Parameters:

• doc (SDFDoc) –

  • A document to which the image should be added. The ‘Doc’ object

  can be obtained using Obj::GetDoc() or PDFDoc::GetSDFDoc().

• buf (string) –

  • The stream or buffer containing image data stored in 1 bit per

  sample format. The image data must not be compressed and must follow PDF format for sample representation (please refer to section 4.8.2 ‘Sample Representation’ in PDF Reference Manual for details).

• width (int) –

  • The width of the image, in samples.

• height (int) –

  • The height of the image, in samples.

• encoder_hints (Obj) –

  • An optional parameter that can be used to fine tune

  compression or to select a different compression algorithm. See Image::Create() for details.

Return type:

Image

Returns:

PDF::Image object representing the embedded ImageMask.

Overload 2:

Create and embed an ImageMask. Notes: see Image::CreateImageMask for details.

Overload 3:

Create and embed an ImageMask. Notes: see Image::CreateImageMask for details.

static CreateSoftMask(args)

Overload 1:

Create and embed a Soft Mask. Embed the raw image data taking into account specified compression hints. A soft-mask image (see “Soft-Mask Images” in PDF Reference Manual) is used as a source of mask shape or mask opacity values in the transparent imaging model.

Parameters:

• doc (SDFDoc) –

  • A document to which the image should be added. The ‘Doc’ object

  can be obtained using Obj::GetDoc() or PDFDoc::GetSDFDoc().

• buf (string) –

  • The stream or buffer containing image data represented in

  DeviceGray color space (i.e. one component per sample). The image data must not be compressed and must follow PDF format for sample representation (please refer to section 4.8.2 ‘Sample Representation’ in PDF Reference Manual for details).

• width (int) –

  • The width of the image, in samples.

• height (int) –

  • The height of the image, in samples.

• bpc (int) –

  • The number of bits used to represent each color component.

• encoder_hints (Obj) –

  • An optional parameter that can be used to fine tune

  compression or to select a different compression algorithm. See Image::Create() for details.

Notes: this feature is available only in PDF 1.4 and higher.

Overload 2:

Create and embed a Soft Mask. Embed the raw image data taking into account specified compression hints. Notes: see Image::CreateSoftMask for details.

Overload 3:

Create and embed a Soft Mask. Embed the raw image data taking into account specified compression hints. Notes: see Image::CreateSoftMask for details.

Export(args)

Overload 1:

Saves this image to a file.

The output image format (TIFF, JPEG, or PNG) will be automatically selected based on the properties of the embedded image. For example, if the embedded image is using CCITT Fax compression, the output format will be TIFF. Similarly, if the embedded image is using JPEG compression the output format will be JPEG. If your application needs to explicitly control output image format you may want to use ExportAsTiff() or ExportAsPng().

Parameters:

filename (string) – string that specifies the path name for the saved image. The filename should not include the extension which will be appended to the filename string based on the output format.

Return type:

int

Returns:

the number indicating the selected image format: (0 - PNG, 1 - TIF, 2 - JPEG).

Overload 2:

Saves this image to the output stream. (0 - PNG, 1 - TIF, 2 - JPEG).

Parameters:

writer (FilterWriter) – A pointer to FilterWriter used to write to the output stream. If the parameter is null, nothing will be written to the output stream, but the function returns the format identifier.

Return type:

int

Returns:

the number indicating the selected image format:

Notes: see the overloaded Image::Export method for more information.

ExportAsPng(args)

Overload 1:

Saves this image to a PNG file.

Parameters:

filename (string) – string that specifies the path name for the saved image. The filename should include the file extension

Overload 2:

Saves this image to a PNG output stream.

Parameters:

writer (FilterWriter) – FilterWriter used to write to the output stream.

ExportAsTiff(args)

Overload 1:

Saves this image to a TIFF file.

Parameters:

filename (string) – string that specifies the path name for the saved image. The filename should include the file extension

Overload 2:

Saves this image to a TIFF output stream.

Parameters:

writer (FilterWriter) – FilterWriter used to write to the output stream.

GetBitsPerComponent()

Return type:

int

Returns:

the number of bits used to represent each color component. Only a single value may be specified; the number of bits is the same for all color components. Valid values are 1, 2, 4, 8, and 16.

GetComponentNum()

Return type:

int

Returns:

the number of color components per sample.

GetDecodeArray()

Return type:

Obj

Returns:

Decode array or NULL if the parameter is not specified. A decode object is an array of numbers describing how to map image samples into the range of values appropriate for the images color space . If ImageMask is true, the array must be either [0 1] or [1 0]; otherwise, its length must be twice the number of color components required by ColorSpace. Default value depends on the color space, See Table 4.36 in PDF Ref. Manual.

GetImageColorSpace()

Convert PDF image to GDI+ Bitmap.

Return type:

ColorSpace

Returns:

GDI+ bitmap from this image. PDFNet creates a GDI+ bitmap that closely matches the original image in terms of the image depth and the number of color channels. PDF color spaces that do not have a counterpart in GDI+ are converted to RGB.

Notes: This method is available only on Windows platforms.

Return type:

ColorSpace

Returns:

The SDF object representing the color space in which image samples are specified or NULL if:

• the image is an image mask

• or is compressed using JPXDecode with missing ColorSpace entry in image dictionary.

The returned color space may be any type of color space except Pattern.

GetImageData()

Return type:

Filter

Returns:

A stream (filter) containing decoded image data

GetImageDataSize()

Return type:

int

Returns:

the size of image data in bytes

GetImageHeight()

Return type:

int

Returns:

the height of the image, in samples.

GetImageRenderingIntent()

Return type:

int

Returns:

The color rendering intent to be used in rendering the image.

GetImageWidth()

Return type:

int

Returns:

the width of the image, in samples.

GetMask()

Return type:

Obj

Returns:

an image XObject defining an image mask to be applied to this image (See ‘Explicit Masking’, 4.8.5), or an array specifying a range of colors to be applied to it as a color key mask (See ‘Color Key Masking’).

If IsImageMask() return true, this method will return NULL.

GetSDFObj()

Return type:

Obj

Returns:

the underlying SDF/Cos object

GetSoftMask()

Return type:

Obj

Returns:

an image XObject defining a Soft Mask to be applied to this image (See section 7.5.4 ‘Soft-Mask Images’ in PDF Reference Manual), or NULL if the image does not have the soft mask.

IsImageInterpolate()

Return type:

boolean

Returns:

a boolean indicating whether image interpolation is to be performed.

IsImageMask()

Return type:

boolean

Returns:

a boolean indicating whether the inline image is to be treated as an image mask.

IsValid()

Return type:

boolean

Returns:

whether this is a valid raster image. If the function returns false the underlying SDF/Cos object is not a valid raster image and this Image object should be treated as null.

SetMask(args)

Overload 1:

Set an Explicit Image Mask.

Parameters:

image_mask (Image) – An Image object which serves as an explicit mask for the base (this) image. The base image and the image mask need not have the same resolution (Width and Height values), but since all images are defined on the unit square in user space, their boundaries on the page will coincide; that is, they will overlay each other. The image mask indicates which places on the page are to be painted and which are to be masked out (left unchanged). Unmasked areas are painted with the corresponding portions of the base image; masked areas are not.

Notes: image_mask must be a valid image mask (i.e. image_mask.IsImageMask() must return true.

Overload 2:

Set a Color Key Mask.

Parameters:

mask (Obj) – is an Cos/SDF array specifying a range of colors to be masked out. Samples in the image that fall within this range are not painted, allowing the existing background to show through. The effect is similar to that of the video technique known as chroma-key. For details of the array format please refer to section 4.8.5 ‘Color Key Masking’ in PDF Reference Manual.

Notes: the current document takes the ownership of the given SDF object.

SetSoftMask(soft_mask)

Set a Soft Mask.

Parameters:

soft_mask (Image) – is a subsidiary Image object defining a soft-mask image (See section 7.5.4 ‘Soft-Mask Images’ in PDF Reference Manual) to be used as a source of mask shape or mask opacity values in the transparent imaging model. The alpha source parameter in the graphics state determines whether the mask values are interpreted as shape or opacity.

e_ascii_hex = 6

e_flate = 3

e_g3 = 4

e_g4 = 5

e_jp2 = 2

e_jpeg = 1

e_none = 0

property mp_image

property thisown

The membership flag

class apryse_sdk.Image2RGB(args)

Bases: Filter

Image2RGB is a filter that can decompress and normalize any PDF image stream (e.g. monochrome, CMYK, etc) into a raw RGB pixel stream.

property thisown

The membership flag

class apryse_sdk.Image2RGBA(args)

Bases: Filter

Image2RGBA is a filter that can decompress and normalize any PDF image stream (e.g. monochrome, CMYK, etc) into a raw RGBA pixel stream.

property thisown

The membership flag

class apryse_sdk.ImageSettings

Bases: object

A class that stores downsampling/recompression settings for color and grayscale images.

ForceChanges(force)

Sets whether image changes that grow the PDF file should be kept. This is off by default.

Parameters:

force (boolean) – if true all image changes will be kept.

ForceRecompression(force)

Sets whether recompression to the specified compression method should be forced when the image is not downsampled. By default the compression method for these images will not be changed.

Parameters:

force (boolean) – if true the compression method for all images will be changed to the specified compression mode

SetCompressionMode(mode)

Sets the output compression mode for this type of image The default value is e_retain

Parameters:

mode (int) – the compression mode to set

SetDownsampleMode(mode)

Sets the downsample mode for this type of image The default value is e_default which will allow downsampling of images

Parameters:

mode (int) – the downsample mode to set

SetImageDPI(maximum, resampling)

Sets the maximum and resampling dpi for images. By default these are set to 144 and 96 respectively.

Parameters:

• maximum (double) – the highest dpi of an image before it will be resampled

• resampling (double) – the image dpi to resample to if an image is encountered over the maximum dpi

SetQuality(quality)

Sets the quality for lossy compression modes from 1 to 10 where 10 is lossless (if possible) the default value is 5

e_default = 1

e_flate = 1

e_jpeg = 2

e_jpeg2000 = 3

e_none = 4

e_off = 0

e_retain = 0

property thisown

The membership flag

apryse_sdk.Image_Create(args)

Overload 1:

Create and embed an Image from an external file taking into account specified compression hints.

By default the function will either pass-through data preserving the original compression or will compress data using Flate compression. It is possible to fine tune compression or to select a different compression algorithm using ‘encoder_hints’ object.

Parameters:

• doc (SDFDoc) –

  • A document to which the image should be added. To obtain

  SDF::Doc from PDFDoc use PDFDoc::GetSDFDoc() or Obj::GetDoc().

• filename (string) –

  • The name of the image file. Currently supported formats are

  JPEG, PNG, GIF, TIFF, BMP, EMF, and WMF. Other raster formats can be embedded by decompressing image data and using other versions of Image::Create(…) method.

• encoder_hints (Obj) –

  • An optional SDF::Obj containing a hint (or an SDF::Array of

    hints) that could be used to select a specific compression method and compression parameters. For a concrete example of how to create encoder hints, please take a look at JBIG2Test and AddImage sample projects. The image encoder accepts the following hints:

  • /JBIG2; SDF::Name(“JBIG2”), An SDF::Name Object with value equal to “JBIG2”. If the

    image is monochrome (i.e. bpc == 1), the encoder will compress the image using JBIG2Decode filter. Note that JBIG2 compression is not recommended for use on scanned text/financial documents or equivalent

  since its lossless nature can lead to similar looking numbers or characters being replaced.

  • [/JBIG2 /Threshold 0.6 /SharePages 50] - Compress a monochrome image using lossy JBIG2Decode

  compression with the given image threshold and by sharing segments from a specified number of pages. The threshold is a doubleing point number in the range from 0.4 to 0.9. Increasing the threshold value will increase image quality, but may increase the file size. The default value for threshold is 0.85. “SharePages” parameter can be used to specify the maximum number of pages sharing a common ‘JBIG2Globals’ segment stream. Increasing the value of this parameter improves compression ratio at the expense of memory usage.

  • [/CCITT] - Compress a monochrome (i.e. bpc == 1) image using CCITT Group 4 compression. This algorithm typically produces

    larger output than JBIG2, but is lossless. This makes it much more suitable for scanned text documents. CCITT is the best option for more general monochrome compression use cases, since JBIG2 has potential to change image content.

  • [/JPEG] - Use JPEG compression with default compression.

  • [/JPEG /Quality 60] - Use JPEG compression with given quality setting. The “Quality”

    value is expressed on the 0..100 scale.

  • [/JPEG2000] - Use JPEG2000 compression to compress a RGB or a grayscale image.<para>

  • [/JP2] - Use JPEG2000 compression with JP2 encoding. JP2 does not support CMYK images.<para>

  • [/Flate] - Use Flate compression with maximum compression at the expense of

    speed.

  • [/Flate /Level 9] - Use Flate compression using specified compression level.

    Compression “Level” must be a number between 0 and 9: 1 gives best speed, 9 gives best compression, 0 gives no compression at all (the input data is simply copied a block at a time).

  • /RAW or [/RAW] - The encoder will not use any compression method and the image

    will be stored in the raw format.

Return type:

Image

Returns:

PDF::Image object representing the embedded image.

Notes: For C++ developers: Current document does not take the ownership of the encoder_hints object. Therefore it is a good programming practice to create encoder_hints object on the stack.

Overload 2:

Create and embed an Image. Embed the raw image data taking into account specified compression hints.

By default the function will compress all images using Flate compression. It is possible to fine tune compression or to select a different compression algorithm using ‘encoder_hints’ object.

Parameters:

• doc (SDFDoc) –

  • A document to which the image should be added. The ‘Doc’ object

  can be obtained using Obj::GetDoc() or PDFDoc::GetSDFDoc().

• buf (unsigned char) –

  • The stream or buffer containing image data. The image data must

  not be compressed and must follow PDF format for sample representation (please refer to section 4.8.2 ‘Sample Representation’ in PDF Reference Manual for details).

• width (int) –

  • The width of the image, in samples.

• height (int) –

  • The height of the image, in samples.

• bpc (int) –

  • The number of bits used to represent each color component.

• color_space (ColorSpace) –

  • The color space in which image samples are represented.

• encoder_hints (Obj) –

  • An optional parameter that can be used to fine tune

  compression or to select a different compression algorithm. See Image::Create() for details.

Return type:

Image

Returns:

PDF::Image object representing the embedded image.

Overload 3:

Create and embed an Image. Embed the raw image data taking into account specified compression hints.

By default the function will compress all images using Flate compression. It is possible to fine tune compression or to select a different compression algorithm using ‘encoder_hints’ object.

Parameters:

• doc (SDFDoc) –

  • A document to which the image should be added. The ‘Doc’ object

  can be obtained using Obj::GetDoc() or PDFDoc::GetSDFDoc().

• buf (unsigned char) –

  • The stream or buffer containing image data. The image data must

  not be compressed and must follow PDF format for sample representation (please refer to section 4.8.2 ‘Sample Representation’ in PDF Reference Manual for details).

• width (int) –

  • The width of the image, in samples.

• height (int) –

  • The height of the image, in samples.

• bpc (int) –

  • The number of bits used to represent each color component.

• color_space (ColorSpace) –

  • The color space in which image samples are represented.

• encoder_hints –

  • An optional parameter that can be used to fine tune

  compression or to select a different compression algorithm. See Image::Create() for details.

Return type:

Image

Returns:

PDF::Image object representing the embedded image.

Overload 4:

Create and embed an Image. Embed the raw image data taking into account specified compression hints. Notes: see Image::Create for details.

Overload 5:

Create and embed an Image. Embed the raw image data taking into account specified compression hints. Notes: see Image::Create for details.

Overload 6:

Create and embed an Image. Embed the raw image data taking into account specified compression hints. Notes: see Image::Create for details.

Overload 7:

Create and embed an Image. Embed the raw image data taking into account specified compression hints. Notes: see Image::Create for details.

Overload 8:

Create and embed an Image. Embed the raw image data taking into account specified compression hints.

Notes: see Image::Create for details. PDFNet takes ownership of the filter

Overload 9:

Create and embed an Image. Embed the raw image data taking into account specified compression hints.

Notes: see Image::Create for details. PDFNet takes ownership of the filter

Overload 10:

Directly embed the image that is already compressed using the Image::InputFilter format. The function can be used to pass-through pre-compressed image data.

Parameters:

• doc (SDFDoc) –

  • A document to which the image should be added. The ‘Doc’ object

  can be obtained using Obj::GetDoc() or PDFDoc::GetSDFDoc().

• buf (string) –

  • The stream or buffer containing compressed image data.

  The compression format must match the input_format parameter.

• width (int) –

  • The width of the image, in samples.

• height (int) –

  • The height of the image, in samples.

• bpc (int) –

  • The number of bits used to represent each color component.

• color_space (ColorSpace) –

  • The color space in which image samples are specified.

• input_format (int) –

  • Image::InputFilter describing the format of pre-compressed

  image data.

Return type:

Image

Returns:

PDF::Image object representing the embedded image.

Overload 11:

Embed the raw image data taking into account specified compression hints. Notes: see the above method for details.

apryse_sdk.Image_CreateImageMask(args)

Overload 1:

Create and embed an Image from any GDI+ Bitmap taking into account specified compression hints.

Notes: see Image::Create for details. This method is available only on Windows platforms.

Parameters:

• doc (SDFDoc) –

  • A document to which the image should be added. The ‘Doc’ object

  can be obtained using Obj::GetDoc() or PDFDoc::GetSDFDoc().

• bmp –

  • GDI+ bitmap.

Return type:

Image

Returns:

PDF::Image object representing the embedded image.

Create and embed an ImageMask. Embed the raw image data taking into account specified compression hints. The ImageMask can be used as a stencil mask for painting in the current color or as an explicit mask specifying which areas of the image to paint and which to mask out. One of the most important uses of stencil masking is for painting character glyphs represented as bitmaps.

Parameters:

• doc (SDFDoc) –

  • A document to which the image should be added. The ‘Doc’ object

  can be obtained using Obj::GetDoc() or PDFDoc::GetSDFDoc().

• buf (string) –

  • The stream or buffer containing image data stored in 1 bit per

  sample format. The image data must not be compressed and must follow PDF format for sample representation (please refer to section 4.8.2 ‘Sample Representation’ in PDF Reference Manual for details).

• width (int) –

  • The width of the image, in samples.

• height (int) –

  • The height of the image, in samples.

• encoder_hints (Obj) –

  • An optional parameter that can be used to fine tune

  compression or to select a different compression algorithm. See Image::Create() for details.

Return type:

Image

Returns:

PDF::Image object representing the embedded ImageMask.

Overload 2:

Create and embed an ImageMask. Notes: see Image::CreateImageMask for details.

Overload 3:

Create and embed an ImageMask. Notes: see Image::CreateImageMask for details.

apryse_sdk.Image_CreateSoftMask(args)

Overload 1:

Create and embed a Soft Mask. Embed the raw image data taking into account specified compression hints. A soft-mask image (see “Soft-Mask Images” in PDF Reference Manual) is used as a source of mask shape or mask opacity values in the transparent imaging model.

Parameters:

• doc (SDFDoc) –

  • A document to which the image should be added. The ‘Doc’ object

  can be obtained using Obj::GetDoc() or PDFDoc::GetSDFDoc().

• buf (string) –

  • The stream or buffer containing image data represented in

  DeviceGray color space (i.e. one component per sample). The image data must not be compressed and must follow PDF format for sample representation (please refer to section 4.8.2 ‘Sample Representation’ in PDF Reference Manual for details).

• width (int) –

  • The width of the image, in samples.

• height (int) –

  • The height of the image, in samples.

• bpc (int) –

  • The number of bits used to represent each color component.

• encoder_hints (Obj) –

  • An optional parameter that can be used to fine tune

  compression or to select a different compression algorithm. See Image::Create() for details.

Notes: this feature is available only in PDF 1.4 and higher.

Overload 2:

Create and embed a Soft Mask. Embed the raw image data taking into account specified compression hints. Notes: see Image::CreateSoftMask for details.

Overload 3:

Create and embed a Soft Mask. Embed the raw image data taking into account specified compression hints. Notes: see Image::CreateSoftMask for details.

class apryse_sdk.Ink(args)

Bases: Markup

An ink annotation (PDF 1.3) represents a freehand “scribble” composed of one or more disjoint paths. When opened, it shall display a pop-up window containing the text of the associated note.

static Create(doc, pos)

Creates a new Ink annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the Ink annotation is added.

• pos (Rect) – A rectangle specifying the Ink annotation’s bounds in default user space units.

Return type:

Ink

Returns:

A newly created blank Ink annotation.

static CreateAnnot(doc, pos)

Erase(pt1, pt2, width)

Erase a rectangle area formed by pt1pt2 with width

Parameters:

• pt1 (Point) – A point object that is one end of the eraser segment

• pt2 (Point) – A point object that is the other end of the eraser segment

• width (double) – The half width of the eraser

Return type:

boolean

Returns:

Whether an ink stroke was erased

GetHighlightIntent()

Retrieves whether the Ink will draw like a highlighter.

Return type:

boolean

Returns:

true if the Ink will draw like a highlighter. (multiply blend mode) If false it will draw in normal mode. (normal blend mode)

GetPathCount()

Returns number of paths in the annotation.

Return type:

int

Returns:

An integer representing the number of paths in the ‘InkList’ entry of the annotation dictionary.

Notes: Each path is an array of Point objects specifying points along the path. When drawn, the points shall be connected by straight lines or curves in an implementation-dependent way.

GetPoint(pathindex, pointindex)

Returns the specific point in a given path.

Parameters:

• pathindex (int) – path index for each the point is returned. Index starts at 0.

• pointindex (int) – index of point in the path. Index starts at 0.

Return type:

Point

Returns:

A Point object for specified path and point index.

Notes: Each path is an array of Point objects specifying points along the path. When drawn, the points shall be connected by straight lines or curves in an implementation-dependent way.

GetPointCount(pathindex)

Returns number of points in a certain stroked path in the InkList.

Parameters:

pathindex (int) – path index for each the point count is returned. Index starts at 0.

Return type:

int

Returns:

An integer representing the number of points in the stroked path of the Ink list.

See also: GetPathCount()

SetHighlightIntent(highlight)

Enables or disables the Ink drawing like a highlighter.

Parameters:

highlight (boolean) – true if the Ink will draw like a highlighter. (multiply blend mode) If false it will draw in normal mode. (normal blend mode)

SetPoint(pathindex, pointindex, pt)

Sets the specific point in the Ink List, adding it if needed.

Parameters:

• pathindex (int) – An unsigned integer indicating the index of the path.

• pointindex (int) – An unsigned integer indicating the index of the point within the stroked path indicated by the parameter “pathindex”.

• pt (Point) – A Point object that is to be assigned.

Notes: Ink annotation contains an array of paths. Each path is an array of Point objects specifying points along the path. When drawn, the points shall be connected by straight lines or curves in an implementation-dependent way.

property thisown

The membership flag

apryse_sdk.Ink_Create(doc, pos)

Creates a new Ink annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the Ink annotation is added.

• pos (Rect) – A rectangle specifying the Ink annotation’s bounds in default user space units.

Return type:

Ink

Returns:

A newly created blank Ink annotation.

apryse_sdk.Ink_CreateAnnot(doc, pos)

class apryse_sdk.Line(args)

Bases: object

TextExtractor::Line object represents a line of text on a PDF page. Each line consists of a sequence of words, and each words in one or more styles.

EndsWithHyphen()

Return type:

boolean

Returns:

true is this line of text ends with a hyphen (i.e. ‘-‘), false otherwise.

GetBBox()

Parameters:

out_bbox – The bounding box for this line (in unrotated page coordinates).

Notes: To account for the effect of page ‘/Rotate’ attribute, transform all points using page.GetDefaultMatrix().

GetCurrentNum()

Return type:

int

Returns:

the index of this line of the current page.

GetFirstWord()

Return type:

Word

Returns:

the first word in the line.

Notes: To traverse the list of all words on this line use word.GetNextWord().

GetFlowID()

Return type:

int

Returns:

The unique identifier for a paragraph or column that this line belongs to. This information can be used to identify which lines/paragraphs belong to which flows.

GetNextLine()

Return type:

Line

Returns:

the next line on the page.

GetNumWords()

Return type:

int

Returns:

The number of words in this line.

GetParagraphID()

Return type:

int

Returns:

The unique identifier for a paragraph or column that this line belongs to. This information can be used to identify which lines belong to which paragraphs.

GetQuad()

Return type:

std::vector< double,std::allocator< double > >

Returns:

The quadrilateral representing a tight bounding box for this line (in unrotated page coordinates).

GetStyle()

Return type:

Style

Returns:

predominant style for this line.

GetWord(word_idx)

Return type:

Word

Returns:

the i-th word in this line.

Parameters:

word_idx (int) – A integer representing the index of the word to get.

IsSimpleLine()

Return type:

boolean

Returns:

true is this line is not rotated (i.e. if the quadrilaterals returned by GetBBox() and GetQuad() coincide).

IsValid()

Return type:

boolean

Returns:

true if this is a valid line, false otherwise.

property mp_line

property thisown

The membership flag

class apryse_sdk.LineAnnot(args)

Bases: Markup

A line annotation (PDF 1.3) is used to display a single straight line on the page. When opened, it should display a pop-up window containing the text of the associated note.

static Create(doc, pos)

Creates a new Line annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds in default user space units.

Return type:

LineAnnot

Returns:

A newly created blank Line annotation.

static CreateAnnot(doc, pos)

GetCaptionPosition()

Returns the caption position of a line.

Return type:

int

Returns:

A cap position value from the “CapPos” enum.

Notes: Caption position describes the annotation’s caption positioning. Default value: Inline See also: CapPos

GetEndPoint()

Returns the coordinates of the end of a line.

Return type:

Point

Returns:

A point specifying the coordinates of the end of the line.

GetEndStyle()

Returns the ending style that applies to the second point of the line.

Return type:

int

Returns:

A enum value from the “EndingStyle”.

Notes: Default value: e_None.

GetIntentType()

Returns the intent type of the line.

Return type:

int

Returns:

An intent type value from the “IntentType” enum.

Notes: Intent type describes the intent of the line annotation. Valid values shall be “e_LineArrow”, which means that the annotation is intended to function as an arrow, and “e_LineDimension”, which means that the annotation is intended to function as a dimension line.

GetLeaderLineExtensionLength()

Returns the leader line extension length of a line.

Return type:

double

Returns:

A number denoting the length of the leader line extension in default user space units.

Notes: The leader line extension length is a non-negative number that shall represents the length of leader line extensions that extend from the line proper 180 degrees from the leader lines. Default value: 0 (no leader line extensions)

GetLeaderLineLength()

Returns the leader line length of a line.

Return type:

double

Returns:

A number denoting the length of the leader line in default user space units.

Notes: Usually if this entry is specified, the line is intended to be a dimension line (see “IT” entry of the annotation dictionary). Leader length is length of leader lines in default user space that extend from each endpoint of the line perpendicular to the line itself. A positive value shall mean that the leader lines appear in the direction that is clockwise when traversing the line from its starting point to its ending point (as specified by L); a negative value shall indicate the opposite direction. Default value: 0 (no leader lines)

GetLeaderLineOffset()

Returns the leader line offset length of a line.

Return type:

double

Returns:

A number denoting the length of the leader line offset in default user space units.

Notes: Leader line offset number is a non-negative number that shall represent the length of the leader line offset, which is the amount of empty space between the endpoints of the annotation and the beginning of the leader lines.

GetShowCaption()

Returns true if caption is to be shown, otherwise false.

Return type:

boolean

Returns:

A boolean value indicating whether the caption will be shown.

Notes: If true, the text specified by the Contents or RCentries shall be replicated as a caption in the appearance of the line. The text shall be rendered in a manner appropriate to the content, taking into account factors such as writing direction. Default value: false.

GetStartPoint()

Returns the coordinates of the start of a line.

Return type:

Point

Returns:

A point specifying the coordinates of the start of the line.

GetStartStyle()

Returns the ending style that applies to the first point of the line.

Return type:

int

Returns:

A enum value from the “EndingStyle”.

Notes: Default value: e_None.

GetTextHOffset()

Returns the horizontal offset of the caption.

Return type:

double

Returns:

A number denoting the horizontal offset of the caption in default user space units.

Notes: The horizontal offset specifies the offset of the caption text from the line’s midpoint, with a positive value indicating offset to the right and a negative value indicating offset to the left. Default value: 0 (no offset from normal horizontal positioning).

GetTextVOffset()

Returns the vertical offset of the caption.

Return type:

double

Returns:

A number denoting the vertical offset of the caption in default user space units.

Notes: The vertical offset specifies the offset of the caption text perpendicular to the annotation line, with a positive value indicating a shift up and a negative value indicating a shift down. Default value: 0 (no offset from normal vertical positioning).

SetCaptionPosition(style)

Sets the caption position of a line. (Optional, PDF 1.7)

Parameters:

style (int) – A caption position value from the “CapPos” enum.

Notes: Caption position describes the annotation’s caption positioning. Default value: Inline See also: CapPos

SetEndPoint(ep)

Sets the coordinates of the end of a line.

Parameters:

ep (Point) –

• A point specifying the coordinates of the end of the line.

SetEndStyle(est)

Sets the ending style that applies to the second point of the line. (Optional; PDF 1.4)

Parameters:

est (int) – A enum value from the “EndingStyle”.

Notes: Default value: e_None.

SetIntentType(it)

Sets the intent type of the line. (For PDF 1.6)

Parameters:

it (int) – An intent type value from the “IntentType” enum.

Notes: Intent type describes the intent of the line annotation. Valid values shall be “e_LineArrow”, which means that the annotation is intended to function as an arrow, and “e_LineDimension”, which means that the annotation is intended to function as a dimension line.

SetLeaderLineExtensionLength(length)

Sets the leader line extension length of a line. (PDF 1.6)

Parameters:

length (double) – A number denoting the length of the leader line extension in default user space units.

Notes: The leader line extension length is a non-negative number that shall represents the length of leader line extensions that extend from the line proper 180 degrees from the leader lines. Default value: 0 (no leader line extensions)

SetLeaderLineLength(length)

Sets the leader line length of a line. (PDF 1.6)

Parameters:

length (double) – A number denoting the length of the leader line in default user space units.

Notes: Usually if this entry is specified, the line is intended to be a dimension line (see “IT” entry of the annotation dictionary). Leader length is length of leader lines in default user space that extend from each endpoint of the line perpendicular to the line itself. A positive value shall mean that the leader lines appear in the direction that is clockwise when traversing the line from its starting point to its ending point (as specified by L); a negative value shall indicate the opposite direction. Default value: 0 (no leader lines)

SetLeaderLineOffset(length)

Sets the leader line offset length of a line. (PDF 1.7)

Parameters:

length (double) – A number denoting the length of the leader line offset in default user space units.

Notes: Leader line offset number is a non-negative number that shall represent the length of the leader line offset, which is the amount of empty space between the endpoints of the annotation and the beginning of the leader lines.

SetShowCaption(showCaption)

Sets the option of whether to show caption.

Parameters:

showCaption (boolean) – A boolean value indicating whether the caption will be shown.

Notes: If true, the text specified by the Contents or RC entries shall be replicated as a caption in the appearance of the line. The text shall be rendered in a manner appropriate to the content, taking into account factors such as writing direction. Default value: false.

SetStartPoint(sp)

Sets the coordinates of the start of a line.

Parameters:

sp (Point) – A point specifying the coordinates of the end of the line.

SetStartStyle(sst)

Sets the ending style that applies to the first point of the line. (Optional; PDF 1.4.)

Parameters:

sst (int) – A enum value from the “EndingStyle”.

Notes: Default value: e_None.

SetTextHOffset(offset)

Sets the horizontal offset of the caption. (For PDF 1.7 )

Parameters:

offset (double) – A number denoting the horizontal offset of the caption in default user space units.

Notes: The horizontal offset specifies the offset of the caption text from the line’s midpoint, with a positive value indicating offset to the right and a negative value indicating offset to the left. Default value: 0 (no offset from normal horizontal positioning).

SetTextVOffset(offset)

Sets the vertical offset of the caption. (For PDF 1.7 )

Parameters:

offset (double) – A number denoting the vertical offset of the caption in default user space units.

Notes: The vertical offset specifies the offset of the caption text perpendicular to the annotation line, with a positive value indicating a shift up and a negative value indicating a shift down. Default value: 0 (no offset from normal vertical positioning).

e_Butt = 5

A short line at the endpoint perpendicular to the line itself

e_Circle = 1

A circle filled with the annotation’s interior color, if any

e_ClosedArrow = 4

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

e_Diamond = 2

A diamond shape filled with the annotation’s interior color, if any

e_Inline = 0

the caption shall be centered inside the line

e_LineArrow = 0

Line is an arrow

e_LineDimension = 1

Line is a dimension

e_None = 9

No special line ending

e_OpenArrow = 3

Two short lines meeting in an acute angle to form an open arrowhead

e_RClosedArrow = 7

A triangular closed arrowhead in the reverse direction from ClosedArrow

e_ROpenArrow = 6

Two short lines in the reverse direction from OpenArrow

e_Slash = 8

A short line at the endpoint approximately 30 degrees clockwise from perpendicular to the line itself

e_Square = 0

A square filled with the annotation’s interior color, if any

e_Top = 1

the caption shall be on top of the line

e_Unknown = 10

Non-standard or invalid ending

e_null = 2

property thisown

The membership flag

apryse_sdk.LineAnnot_Create(doc, pos)

Creates a new Line annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds in default user space units.

Return type:

LineAnnot

Returns:

A newly created blank Line annotation.

apryse_sdk.LineAnnot_CreateAnnot(doc, pos)

class apryse_sdk.Link(args)

Bases: Annot

A link annotation represents either a hypertext link to a destination elsewhere in the document or an action to be performed.

static Create(args)

Overload 1:

Creates a new Link annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the Link annotation is added.

• pos (Rect) – A rectangle specifying the Link annotation’s bounds in default user space units.

Return type:

Link

Returns:

A newly created blank Link annotation.

Overload 2:

Creates a new Link annotation.

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds in default user space units.

• action (Action) – Action for the link annotation.

Return type:

Link

Returns:

A new Link annotation.

static CreateAnnot(args)

GetAction()

Returns the Action of the Link Annotation.

Return type:

Action

Returns:

An Action object of the Link annotation.

Notes: The return value is an action that shall be performed when the link annotation is activated

GetHighlightingMode()

Returns the highlighting mode of this Link annotation.

Return type:

int

Returns:

the highLighting mode as a value of the enum “HighlightingMode”.

Notes: The annotation’s highlighting mode is the visual effect that shall be used when the mouse button is pressed or held down inside its active area.

static GetNormalizedUrl(url)

Prepends http:// to a string if it does not contain :// or . This can be important when passing a url to other APIs that expect a URI scheme.

Parameters:

url (string) – The string to possibly be prepended

Return type:

string

Returns:

The string that is possibly been prepended.

GetQuadPoint(idx)

Returns the QuadPoint located at a certain index of the QuadPoint array of the Link annotation.

Parameters:

idx (int) – The index of the QuadPoint, starts at zero and should be less than the return value of GetQuadPointCount().

Return type:

QuadPoint

Returns:

The QuadPoint located at a certain index of the QuadPoint array of the Link annotation.

Notes: An array of n QuadPoints specifying the coordinates of n quadrilaterals in default user space that comprise the region in which the link should be active. The coordinates specifying the four vertices of the quadrilateral are in counterclockwise order. For orientation purposes, the bottom of a quadrilateral is the line formed by p1 and p2 of the QuadPoint. QuadPoints shall be ignored if any coordinate in the array lies outside the region specified by Rect.

GetQuadPointCount()

Returns the number of QuadPoints in the ‘QuadPoints’ array of the Link annotation.

Return type:

int

Returns:

The number of QuadPoints.

Notes: An array of n QuadPoints specifying the coordinates of n quadrilaterals in default user space that comprise the region in which the link should be active. The coordinates specifying the four vertices of the quadrilateral are in counterclockwise order. For orientation purposes, the bottom of a quadrilateral is the line formed by p1 and p2 of the QuadPoint. QuadPoints shall be ignored if any coordinate in the array lies outside the region specified by Rect.

RemoveAction()

Removes this annotation’s action.

SetAction(action)

Sets the Action of the Link Annotation. (Optional; PDF 1.1 )

Parameters:

action (Action) – An Action object that shall be associated with this Link annotation.

Notes: The parameter is an action that shall be performed when the link annotation is activated.

SetHighlightingMode(mode)

Sets the highlighting mode for this Link annotation. (Optional; PDF 1.2 )

Parameters:

mode (int) – the mode as a value of the enum “HighlightingMode”.

Notes: The annotation’s highlighting mode is the visual effect that shall be used when the mouse button is pressed or held down inside its active area.

SetQuadPoint(idx, qp)

Set the QuadPoint to be located at a certain index of the QuadPoint array of the Link annotation. (Optional; PDF 1.6 )

Parameters:

• idx (int) – The index of the QuadPoint, starts at zero and should be less than the return value of GetQuadPointCount().

• qp (QuadPoint) – The QuadPoint to be stored in the annotation.

Notes: An array of n QuadPoints specifying the coordinates of n quadrilaterals in default user space that comprise the region in which the link should be active. The coordinates specifying the four vertices of the quadrilateral are in counterclockwise order. For orientation purposes, the bottom of a quadrilateral is the line formed by p1 and p2 of the QuadPoint. QuadPoints shall be ignored if any coordinate in the array lies outside the region specified by Rect.

e_invert = 1

e_none = 0

e_outline = 2

e_push = 3

property thisown

The membership flag

apryse_sdk.Link_Create(args)

Overload 1:

Creates a new Link annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the Link annotation is added.

• pos (Rect) – A rectangle specifying the Link annotation’s bounds in default user space units.

Return type:

Link

Returns:

A newly created blank Link annotation.

Overload 2:

Creates a new Link annotation.

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds in default user space units.

• action (Action) – Action for the link annotation.

Return type:

Link

Returns:

A new Link annotation.

apryse_sdk.Link_CreateAnnot(args)

apryse_sdk.Link_GetNormalizedUrl(url)

Prepends http:// to a string if it does not contain :// or . This can be important when passing a url to other APIs that expect a URI scheme.

Parameters:

url (string) – The string to possibly be prepended

Return type:

string

Returns:

The string that is possibly been prepended.

class apryse_sdk.List(args, kwargs)

Bases: ContentNode

A class representing a list in the document content tree.

AddItem()

Add a new list item to the list.

Return type:

ListItem

Returns:

The ListItem object representing the newly added item.

ContinueList()

Continues the logical continuation of a particular list, even if other non-list content items have been created since the last call to AddItem(). This method is useful when splitting a sublist and wanting to continue the new items as part of the original sublist hierarchy.

Note: Without calling ContinueList(), new list items created after a split (e.g., a split paragraph) would be added to the main list structure (above the split) based on their natural positions in the list/sublist hierarchy.

Example usage: To continue a root-level list after a split, call ContinueList() on the root-level list.

GetIndentationLevel()

Get the indentation level of the list.

Return type:

int

Returns:

The indentation level.

GetLabelStyle()

Get the text style element for the list item labels.

Return type:

TextStyledElement

Returns:

The TextStyledElement representing the label style.

GetListIdentifier()

Get the identifier of the list.

Return type:

int

Returns:

The list identifier.

SetNumberFormat(args)

Overload 1:

Set the number format of the list.

Parameters:

format (int) – The number format to set for the list.

Overload 2:

Set the number format of the list with a custom suffix and cascade flag.

Parameters:

• format (int) – The number format to set for the list.

• suffix (string) – The suffix to append to the list item number.

• cascade (boolean) – If true, the number format will be applied to nested lists as well.

SetStartIndex(idx)

Set the start index for the list items.

Parameters:

idx (int) – The start index value.

e_cardinal_text = 10

e_chinese_counting = 8

e_chinese_counting_thousand = 9

e_decimal = 1

e_decimal_zero = 11

e_lower_letter = 4

e_lower_roman = 2

e_none = 0

e_ordinal = 6

e_ordinal_text = 7

e_upper_letter = 5

e_upper_roman = 3

property m_impl

property thisown

The membership flag

class apryse_sdk.ListBoxWidget(args)

Bases: Widget

An object representing a List Box used in a PDF Form.

AddOption(value)

Adds option to List Box Widget.

Parameters:

value (string) – The option to add

AddOptions(opts)

Adds multiple options to List Box Widget.

Parameters:

opts (std::vector< std::string,std::allocator< std::string > >) – The options to add.

static Create(args)

Overload 1:

Creates a new List Box Widget annotation, in the specified document.

Parameters:

• doc (PDFDoc) – The document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds, specified in user space coordinates.

• field_name (string) – The name of the field for which to create a List Box Widget

Return type:

ListBoxWidget

Returns:

A newly created blank List Box Widget annotation.

Overload 2:

Creates a new List Box Widget annotation, in the specified document.

Parameters:

• doc (PDFDoc) – The document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds, specified in user space coordinates.

• field (Field) – the field for which to create a List Box Widget

Return type:

ListBoxWidget

Returns:

A newly created blank List Box Widget annotation.

GetOptions()

Gets all options of the List Box widget.

Return type:

std::vector< std::string,std::allocator< std::string > >

Returns:

The options of the List Box widget

GetSelectedOptions()

Gets all selected options in the List Box widget.

Return type:

std::vector< std::string,std::allocator< std::string > >

Returns:

The selected options of the List Box widget

RemoveOption(value)

Removes the option from List Box widget.

Parameters:

value (string) – The option to remove.

ReplaceOptions(new_opts)

Replaces the current List Box widget options with a new set.

Parameters:

new_opts (std::vector< std::string,std::allocator< std::string > >) – The new set of options to use.

SetSelectedOptions(selected_opts)

Sets the options for the ListBox widget.

Parameters:

selected_opts (std::vector< std::string,std::allocator< std::string > >) – The options to select.

property thisown

The membership flag

apryse_sdk.ListBoxWidget_Create(args)

Overload 1:

Creates a new List Box Widget annotation, in the specified document.

Parameters:

• doc (PDFDoc) – The document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds, specified in user space coordinates.

• field_name (string) – The name of the field for which to create a List Box Widget

Return type:

ListBoxWidget

Returns:

A newly created blank List Box Widget annotation.

Overload 2:

Creates a new List Box Widget annotation, in the specified document.

Parameters:

• doc (PDFDoc) – The document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds, specified in user space coordinates.

• field (Field) – the field for which to create a List Box Widget

Return type:

ListBoxWidget

Returns:

A newly created blank List Box Widget annotation.

class apryse_sdk.ListItem(args, kwargs)

Bases: ContentNode

A class representing an item in a list in the document content tree.

AddList()

Add a nested list to the list item.

Return type:

List

Returns:

The List object representing the nested list.

AddParagraph(args)

Overload 1:

Add a new paragraph to the list item.

Return type:

Paragraph

Returns:

The Paragraph object representing the newly added paragraph.

Overload 2:

Add a new paragraph with the specified text to the list item.

Parameters:

text (string) – The text content of the paragraph.

Return type:

Paragraph

Returns:

The Paragraph object representing the newly added paragraph.

GetIndentationLevel()

Get the indentation level of the list item.

Return type:

int

Returns:

The indentation level.

GetItemIndex()

Get the index of the list item within the parent list.

Return type:

int

Returns:

The index of the list item.

GetListIdentifier()

Get the identifier of the list.

Return type:

int

Returns:

The list identifier.

property m_impl

property thisown

The membership flag

class apryse_sdk.MappedFile(filename)

Bases: Filter

MappedFile is a utility class to read files on a file system. Because MappedFile file is derived from pdftron.Filters.Filter you can directly chain MappedFile objects to other ‘pdftron.Filters’.

MappedFile objects support random access to files using the Seek method. Seek allows the read/write position to be moved to any position within the file. This is done through a shared memory mapped chunk manager. The byte offset is relative to the seek reference point, which can be the beginning, the current position, or the end of the underlying file, as represented by the three properties of the Filter.ReferencePos class.

MappedFile objects are thread-safe, meaning separate copies of a MappedFile can Seek to different locations in the file, without conflicting with one another.

Disk files always support random access. At the time ofruction, the CanSeek() property value is set to true or false depending on the underlying file type.

Notes: .NET or Java applications should explicitly Close() files when they are not needed. If the files are not closed or disposed this may lead to the resource exhaustion.

static Equivalent(ph1, ph2)

Check is the two file paths are equivalent (i.e. they refer to the same file on disc.

Return type:

boolean

Returns:

true if the two files share the same filename, false otherwise.

FileSize()

Return type:

int

Returns:

the size of the current file.

property thisown

The membership flag

apryse_sdk.MappedFile_Equivalent(ph1, ph2)

Check is the two file paths are equivalent (i.e. they refer to the same file on disc.

Return type:

boolean

Returns:

true if the two files share the same filename, false otherwise.

class apryse_sdk.Markup(args)

Bases: Annot

Markup is a base class for a number of annotations types that are used to mark up PDF documents. These annotations have text that appears as part of the annotation and may be displayed in other ways by a conforming reader, such as in a Comments pane. Markup annotations may be divided into the following groups: - Free text annotations display text directly on the page.

The annotation’s Contents entry specifies the displayed text.

• Most other markup annotations have an associated pop-up window that may contain text. The annotation’s Contents entry specifies the text that shall be displayed when the pop-up window is opened. These include text, line, square, circle, polygon, polyline, highlight,underline, squiggly-underline, strikeout, rubber stamp, caret, ink, and file attachment annotations.

• Sound annotations do not have a pop-up window but may also have associated text specified by the Contents entry.

• A subset of markup annotations are intended to markup text of a document (e.g. highlight, strikeout, jagged, underline) and they are derived from TextMarkup base class.

Notes: The pop-up annotation type must not appear by itself; it must be associated with a markup annotation that uses it to display text.

The meaning of an annotation’s Contents entry varies by annotation type. Typically, it is the text that shall be displayed for the annotation or, if the annotation does not display text, an alternate description of the annotation’s contents in human-readable form. When separating text into paragraphs, a CARRIAGE RETURN (0Dh) must be used.

GetBorderEffect()

Return type:

int

Returns:

the border effect of the markup annotation. Default value: e_None.

Beginning with PDF 1.5, some annotations (square, circle, and polygon) may have a ‘BE’ entry, which is a border effect dictionary that specifies an effect that shall be applied to the border of the annotations. Beginning with PDF 1.6, the free text annotation may also have a BE entry. Notes: When “e_Cloudy” is chosen,the width and dash array specified by the annotation’s BorderStyle entry needs to be taken into consideration.

GetBorderEffectIntensity()

Return type:

double

Returns:

A number describing the intensity of the border effect, in the range 0 to 2.

Beginning with PDF 1.5, some annotations (square, circle, and polygon) may have a ‘BE’ entry, which is a border effect dictionary that specifies an effect that shall be applied to the border of the annotations. Beginning with PDF 1.6, the free text annotation may also have a BE entry.

GetContentRect()

Returns the inner bounding rectangle of the Markup annotation.

Return type:

Rect

Returns:

A rectangle specifying the region where content should be displayed.

Notes: This rectangle can be same as or inside of the annotation’s rectangle. If it is smaller, such a difference may occur in situations where a border effect causes the size of the annotation Rect entry to increase beyond that of the rectangle. For FreeText annotation with a callout, content rectangle specifies an inner region for the text to be displayed. According to PDF Reference Manual content rectangle is not the property that is expected for Markup annotations in general, but it applies to many derived annotation classes (FreeText,Square,Circle,Caret) and therefore get()/set() methods are provided in the base class Markup. Annotations that do not use this property will ignore the content rectangle (‘RD’ entry), if present in their annotation dictionary.

GetCreationDates()

Return type:

Date

Returns:

The creation date for the markup annotation.

Notes: This corresponds to the ‘CreationDate’ field of the markup annotation’s dictionary.

GetInteriorColor()

Returns the interior color of the annotation.

Return type:

ColorPt

Returns:

A ColorPt object that denotes the color of the annotation.

Notes: The color can be in different color spaces: Gray, RGB, or CMYK. Call “GetInteriorColorCompNum” to access the color space information. According to PDF Reference Manual interior color is not the property that is expected for Markup annotations in general, but it applies to many derived annotations (Line,Square,Circle,Polygon,PolyLine,Redaction) and therefore get()/set() methods are provided in the base class Markup. Annotations that do not use interior color will ignore the interior color (‘IC’ entry), if present in their annotation dictionary. In case no color is specified, CMYK white is returned.

GetInteriorColorCompNum()

Returns the number indicating the interior color space of the annotation.

Return type:

int

Returns:

An integer indicating the number of channels forming the color space. 3 corresponds to RGB, 4 corresponds to CMYK, and 1 corresponds to Gray. If the interior is transparent, the return value is 0.

GetOpacity()

Return type:

double

Returns:

The opacity value. Default value: 1.0.

Notes: This value is applied to all visible elements of the annotation in its closed state (including its background and border) but not to the pop-up window that appears when the annotation is opened. When an appearance stream is presented with the annotation, this entry is ignored.(However, if the compliant viewer regenerates the annotation’s appearance stream, it may incorporate this Opacity entry into the stream’s content.) This corresponds to the ‘CA’ field of the annotation’s dictionary.

GetPadding()

Returns the rectangle difference between overall annotation rectangle and content rectangle.

Return type:

Rect

Returns:

A set of four numbers represented as a Rect struct.

Notes: The four numbers of the returning struct specify the difference between two rectangles: the Rect entry of the annotation and the actual bounding box of the underlying rectangle. Such a difference may occur in situations where a border effect causes the size of the annotation Rect entry to increase beyond that of the rectangle. The four numbers of the returning struct correspond to the differences in default user space, between the left, top, right, and bottom of the two above mentioned rectangles. GetPadding() and GetContentRectangle() both use ‘RD’ entry of the annotation dictionary, but represent it to user in different ways. See also: GetContentRect()

GetPopup()

Returns the Popup object associated with this markup annotation.

Return type:

Popup

Returns:

A Popup object that is associated with this markup annotation.

Notes: The Popup is An indirect reference to a pop-up annotation for entering or editing the text associated with this annotation.

GetSubject()

Returns the subject of the Markup annotation. (PDF 1.5)

Return type:

string

Returns:

A string representing the subject of the Markup annotation.

Notes: The subject is a short piece of text description about the annotation. This corresponds to the ‘Subj’ field of the annotation’s dictionary.

GetTitle()

Returns the title of the markup annotation.

Return type:

string

Returns:

A string representing the title of the markup annotation, or null is the title is not specified.

Notes: The title is The text label that is displayed in the title bar of the annotation’s pop-up window when open and active Markup annotation. This entry is also used to identify the user who added the annotation. It corresponds to the ‘T’ field of the annotation’s dictionary.

RotateAppearance(angle)

Rotates the appearance of the Markup annotation.

Parameters:

angle (double) – The new rotation

Notes: Apply a rotation to an existing appearance. This rotation will be reflected in the bounding rect of the annot (which will be updated), but not in any other part of the annotation dictionary. This will effectively create a custom appearance for the annotation, and any subsequent calls to RefreshAppearance will clear this transformation.

SetBorderEffect(args)

Sets the border effect of the markup annotation. (Optional; PDF 1.5 )

Beginning with PDF 1.5, some annotations (square, circle, and polygon) may have a ‘BE’ entry, which is a border effect dictionary that specifies an effect that shall be applied to the border of the annotations. Beginning with PDF 1.6, the free text annotation may also have a BE entry.

Parameters:

effect (int) – An entry from the enum “BorderEffect” that represents the border effect of the Markup annotation. Default value: e_None.

Notes: When “e_Cloudy” is chosen,the width and dash array specified by the annotation’s BorderStyle entry needs to be taken into consideration.

SetBorderEffectIntensity(intensity=0)

Sets the border effect intensity of the markup annotation. (Optional; valid only if Border effect is Cloudy)

Beginning with PDF 1.5, some annotations (square, circle, and polygon) may have a ‘BE’ entry, which is a border effect dictionary that specifies an effect that shall be applied to the border of the annotations. Beginning with PDF 1.6, the free text annotation may also have a BE entry.

Parameters:

intensity (double) – A number describing the intensity of the border effect, in the range 0 (which is default) to 2.

Notes: this parameter applies only if Border effect is e_Cloudy.

SetContentRect(cr)

Sets the inner bounding rectangle of the Markup annotation. (Optional)

Parameters:

cr (Rect) – A Rect struct to be assign to the ‘RD’ entry of the annotation dictionary.

Notes: This rectangle can be same as or inside of the annotation’s rectangle. If it is smaller, such a difference may occur in situations where a border effect causes the size of the annotation Rect entry to increase beyond that of the rectangle. For FreeText annotation with a callout, content rectangle specifies an inner region for the text to be displayed. According to PDF Reference Manual content rectangle is not the property that is expected for Markup annotations in general, but it applies to many derived annotation classes (FreeText,Square,Circle,Caret) and therefore get()/set() methods are provided in the base class Markup. Annotations that do not use this property will ignore the content rectangle (‘RD’ entry), if present in their annotation dictionary.

SetCreationDates(dt)

Sets the creation date for the markup annotation. (Optional; PDF 1.5 )

Parameters:

dt (Date) – A Date object indicating the date the markup annotation is created.

Notes: This corresponds to the ‘CreationDate’ field of the markup annotation’s dictionary.

SetInteriorColor(c, CompNum)

Sets the interior color of the Markup annotation.

Parameters:

• c (ColorPt) – A ColorPt object that denotes the color of the Markup annotation.

• CompNum (int) – An integer indicating the number of channels forming the color space used. It also defines the length of the array to be allocated for storing the entries of c.

Notes: It is necessary to make sure the consistency between the type of parameter c and the value of parameter CompNum. RGB ColorPt corresponds to 3, CMYK ColorPt corresponds to 4, Gray ColorPt corresponds to 1, and transparent corresponds to 0. According to PDF Reference Manual interior color is not the property that is expected for Markup annotations in general, but it applies to many derived annotation classes and therefore get()/set() methods are provided in the base class Markup. Annotations that do not use interior color will ignore the interior color (‘IC’ entry), if present in their annotation dictionary.

Entries out of the specified color space array length will be discarded. Missing entries for a specified color space will lead to potential exceptions.

SetOpacity(op)

Sets the opacity value for the annotation. (Optional; PDF 1.4 )

Parameters:

op (double) – A number indicating the Markup annotation’s opacity value. Default value: 1.0.

Notes: This value is applied to all visible elements of the annotation in its closed state (including its background and border) but not to the pop-up window that appears when the annotation is opened. When an appearance stream is presented with the annotation, this entry is ignored.(However, if the compliant viewer regenerates the annotation’s appearance stream, it may incorporate this Opacity entry into the stream’s content.) This corresponds to the ‘CA’ field of the annotation’s dictionary.

SetPadding(args)

SetPopup(ppup)

Sets the Popup object associated with this markup annotation. (Optional; PDF 1.3 )

Parameters:

ppup (Popup) – A Popup object that is associated with this markup annotation.

Notes: the Popup is An indirect reference to a pop-up annotation for entering or editing the text associated with this annotation.

SetSubject(contents)

Sets subject of the Markup annotation. (Optional; PDF 1.5 )

Parameters:

contents (string) – A string representing the subject of the Markup annotation.

Notes: The subject is a short piece of text description about the annotation. This corresponds to the ‘Subj’ field of the annotation’s dictionary.

SetTitle(args)

Overload 1:

Sets the title of the markup annotation. (Optional; PDF 1.1)

Parameters:

title (string) – A string.

Notes: The title is The text label that is displayed in the title bar of the annotation’s pop-up window when open and active Markup annotation. This entry is also used to identify the user who added the annotation. It corresponds to the ‘T’ field of the annotation’s dictionary.

Overload 2:

Sets the title of the markup annotation. (Optional; PDF 1.1)

Parameters:

title (string) – A string.

Notes: The title is The text label that is displayed in the title bar of the annotation’s pop-up window when open and active Markup annotation. This entry is also used to identify the user who added the annotation. It corresponds to the ‘T’ field of the annotation’s dictionary.

e_Cloudy = 1

Use “cloudy” border.

e_None = 0

No effect.

property thisown

The membership flag

class apryse_sdk.Matrix2D(args)

Bases: TRN_matrix2d

2D Matrix

A Matrix2D object represents a 3x3 matrix that, in turn, represents an affine transformation. A Matrix2D object stores only six of the nine numbers in a 3x3 matrix because all 3x3 matrices that represent affine transformations have the same third column (0, 0, 1).

Affine transformations include rotating, scaling, reflecting, shearing, and translating. In PDFNet, the Matrix2D class provides the foundation for performing affine transformations on vector drawings, images, and text.

A transformation matrix specifies the relationship between two coordinate spaces. By modifying a transformation matrix, objects can be scaled, rotated, translated, or transformed in other ways.

A transformation matrix in PDF is specified by six numbers, usually in the form of an array containing six elements. In its most general form, this array is denoted [a b c d h v]; The following table lists the arrays that specify the most common transformations:

• Translations are specified as [1 0 0 1 tx ty], where tx and ty are the distances to translate the origin of the coordinate system in the horizontal and vertical dimensions, respectively.

• Scaling is obtained by [sx 0 0 sy 0 0]. This scales the coordinates so that 1 unit in the horizontal and vertical dimensions of the new coordinate system is the same size as sx and sy units, respectively, in the previous coordinate system.

• Rotations are produced by [cos(A) sin(A) -sin(A) cos(A) 0 0], which has the effect of rotating the coordinate system axes by an angle ‘A’ counterclockwise.

• Skew is specified by [1 tan(A) tan(B) 1 0 0], which skews the x axis by an angle A and the y axis by an angle B.

Matrix2D elements are positioned as follows :

m_a m_b 0 |

m_c m_d 0 |

m_h m_v 1 |

A single Matrix2D object can store a single transformation or a sequence of transformations. The latter is called a composite transformation. The matrix of a composite transformation is obtained by multiplying (concatenating) the matrices of the individual transformations. Because matrix multiplication is not commutative-the order in which matrices are multiplied is significant. For example, if you first rotate, then scale, then translate, you get a different result than if you first translate, then rotate, then scale.

For more information on properties of PDF matrices please refer to PDF Reference Manual (Sections 4.2 ‘Coordinate Systems’ and 4.2.3 ‘Transformation Matrices’)

The following sample illustrates how to use Matrix2D in order to position
an image on the page. Note that PDFNet uses the same convention of matrix
multiplication used in PostScript and OpenGL.

        Element element = eb.CreateImage(Image(...));
        double deg2rad = 3.1415926535 / 180.0;

        Matrix2D mtx = Matrix2D(1, 0, 0, 1, 0, 200); // Translate
        mtx = Matrix2D(300, 0, 0, 200, 0, 0);    // Scale
        mtx = Matrix2D::RotationMatrix( 90  deg2rad ); // Rotate
        element.GetGState().SetTransform(mtx);
        writer.WritePlacedElement(element);

The following sample sample illustrates how to use Matrix2D in order to calculate
absolute positioning for the text on the page.
...
Matrix2D text_mtx = text_element.GetTextMatrix();
double x, y;
for (CharIterator itr = text_element.GetCharIterator(); itr.HasNext(); itr.Next()) {
  x = itr.Current().x; // character positioning information
  y = itr.Current().y;
  // Get current transformation matrix (CTM)
  Matrix2D ctm = text_element.GetCTM();

  // To get the absolute character positioning information concatenate current
  // text matrix with CTM and then multiply relative positioning coordinates with
  // the resulting matrix.
  Matrix2D mtx = ctm  text_mtx;
  mtx.Mult(x, y);
}

Concat(a, b, c, d, h, v)

The Concat method updates this matrix with the product of itself and another matrix specified through an argument list.

Parameters:

• a (double) – the matrix element in the first row, first column.

• b (double) – the matrix element in the first row, second column.

• c (double) – the matrix element in the second row, first column.

• d (double) – the matrix element in the second row, second column.

• h (double) – the matrix element in the third row, first column.

• v (double) – the matrix element in the third row, second column.

static IdentityMatrix()

Create identity matrix (1 0 0 1 0 0)

Inverse()

Return type:

Matrix2D

Returns:

If this matrix is invertible, the Inverse method returns its inverse matrix.

IsEquals(m)

IsNotEquals(m)

Mult(pt)

Transform/multiply the point (in_out_x, in_out_y) using this matrix

Multiply(m)

PostTranslate(h, v)

Updates this matrix by concatenating a translation matrix. M’ = M T(h, v). It is equivalent to this.Concat(1,0,0,1,h,v).

Parameters:

• h (double) – the horizontal component of the translation.

• v (double) – the vertical component of the translation.

PreTranslate(h, v)

Updates this matrix to the concatenation of a translation matrix and the original matrix. M’ = T(h, v) M. It is equivalent to this.m_h += h; this.m_v += v.

Parameters:

• h (double) – the horizontal component of the translation.

• v (double) – the vertical component of the translation.

static RotationMatrix(angle)

Return type:

Matrix2D

Returns:

A rotation matrix for a given angle.

Parameters:

angle (double) – the angle of rotation in radians. Positive values specify clockwise rotation.

Scale(h, v)

The Scale method updates this matrix with the product of itself and a scaling matrix.

Parameters:

• h (double) – the horizontal scale factor.

• v (double) – the vertical scale factor

Set(a, b, c, d, h, v)

The Set method sets the elements of this matrix.

Parameters:

• a (double) – the matrix element in the first row, first column.

• b (double) – the matrix element in the first row, second column.

• c (double) – the matrix element in the second row, first column.

• d (double) – the matrix element in the second row, second column.

• h (double) – the matrix element in the third row, first column.

• v (double) – the matrix element in the third row, second column.

Translate(h, v)

Updates this matrix with the product of itself and a translation matrix (i.e. it is equivalent to this.m_h += h; this.m_v += v).

Parameters:

• h (double) – the horizontal component of the translation.

• v (double) – the vertical component of the translation.

Notes: This method is deprecated. Please use PreTranslate or PostTranslate instead. The behavior of this method is identical to PreTranslate, but PostTranslate will be more suitable for some use cases.

static ZeroMatrix()

Create zero matrix (0 0 0 0 0 0)

property thisown

The membership flag

apryse_sdk.Matrix2D_IdentityMatrix()

Create identity matrix (1 0 0 1 0 0)

apryse_sdk.Matrix2D_RotationMatrix(angle)

Return type:

Matrix2D

Returns:

A rotation matrix for a given angle.

Parameters:

angle (double) – the angle of rotation in radians. Positive values specify clockwise rotation.

apryse_sdk.Matrix2D_ZeroMatrix()

Create zero matrix (0 0 0 0 0 0)

class apryse_sdk.MemoryFilter(buf_sz, is_input)

Bases: Filter

MemoryFilter is a memory buffer that can be used as a source or a sink Filter in the Filter pipeline. When a MemoryFilter is the source, other filters can read data stored in memory; When MemoryFilter is a sink, other filters generate data which is then pushed in a memory buffer owned by MemoryFilter (MemoryFilter makes sure that there is enough space to accommodate all data).

GetBuffer()

Notes: MemoryFilter specific function.

Return type:

UChar

Returns:

a pointer to the beginning of the buffer. Use method Count() to determine the number of bytes written to or read from MemoryFilter.

SetAsInputFilter()

Notes: MemoryFilter specific function used to change filter mode from output to input. The utility function is useful in cases when and output data buffer should be converted to an input stream.

The function has no effect on an input MemoryFilter.

property thisown

The membership flag

class apryse_sdk.MonoImageSettings

Bases: object

A class that stores image downsampling/recompression settings for monochrome images.

ForceChanges(force)

Sets whether image changes that grow the PDF file should be kept. This is off by default.

Parameters:

force (boolean) – if true all image changes will be kept.

ForceRecompression(force)

Sets whether recompression to the specified compression method should be forced when the image is not downsampled. By default the compression method for these images will not be changed.

Parameters:

force (boolean) – if true the compression method for all images will be changed to the specified compression mode

SetCompressionMode(mode)

Sets the output compression mode for monochrome images The default value is e_ccitt (CCITT group 4 compression)

Parameters:

mode (int) – the compression mode to set

SetDownsampleMode(mode)

Sets the downsample mode for monochrome images The default value is e_default

Parameters:

mode (int) – the compression mode to set

SetImageDPI(maximum, resampling)

Sets the maximum and resampling dpi for monochrome images. By default these are set to 144 and 96 respectively.

Parameters:

• maximum (double) – the highest dpi of an image before it will be resampled

• resampling (double) – the image dpi to resample to if an image is encountered over the maximum dpi

SetJBIG2Threshold(jbig2_threshold)

Sets the quality for lossy compression modes from 1 to 10 where 10 is lossless (if possible). The default value for JBIG2 is 8.5. The setting is ignored for FLATE.

e_ccitt = 3

e_default = 1

e_flate = 1

e_jbig2 = 0

e_none = 2

e_off = 0

property thisown

The membership flag

class apryse_sdk.Movie(args)

Bases: Annot

A movie annotation contains animated graphics and sound to be presented on the computer screen and through the speakers. When the annotation is activated, the movie is played.

static Create(doc, pos)

Creates a new Movie annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the Movie annotation is added.

• pos (Rect) – A rectangle specifying the Movie annotation’s bounds in default user space units.

Return type:

Movie

Returns:

A newly created blank Movie annotation.

static CreateAnnot(doc, pos)

GetTitle()

Returns the title of the Movie Annotation.

Return type:

string

Returns:

A string representing the title of the Movie Annotation.

Notes: Movie actions may use this title to reference the movie annotation.

IsToBePlayed()

Returns the option of whether the Movie is to be played.

Return type:

boolean

Returns:

a boolean value indicating if the movie is to be played.

Notes: IsToBePlayed is a flag specifying whether to play the movie when the annotation is activated. The movie shall be played using default activation parameters. If the value is false, the movie shall not be played. Default value: true.

SetTitle(title)

Sets the title of the Movie Annotation. (Optional)

Parameters:

title (string) – A string representing the title of the Movie Annotation.

Notes: Movie actions may use this title to reference the movie annotation.

SetToBePlayed(isplay=True)

Sets the option of whether the Movie is to be played. (Optional)

Parameters:

isplay (boolean) – A boolean value telling if the movie is to be played. Default value: true.

Notes: IsToBePlayed is a flag specifying whether to play the movie when the annotation is activated. The movie shall be played using default activation parameters. If the value is false, the movie shall not be played. Default value: true.

property thisown

The membership flag

apryse_sdk.Movie_Create(doc, pos)

Creates a new Movie annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the Movie annotation is added.

• pos (Rect) – A rectangle specifying the Movie annotation’s bounds in default user space units.

Return type:

Movie

Returns:

A newly created blank Movie annotation.

apryse_sdk.Movie_CreateAnnot(doc, pos)

class apryse_sdk.NameTree(args)

Bases: object

A NameTree is a common data structure in PDF. See section 3.8.5 ‘Name Trees’ in PDF Reference Manual for more details.

A name tree serves a similar purpose to a dictionary - associating keys and values - but by different means. NameTrees allow efficient storage of very large association collections (string/Obj maps). A NameTree can have many more entries than a SDF/Cos dictionary can.

NameTree-s use SDF/Cos-style strings (not null-terminated C strings), which may use Unicode encoding etc.

PDFDoc doc("../Data/PDFReference.pdf");
NameTree dests = NameTree::Find(doc.GetSDFDoc(), "Dests");
if (dests.IsValid()) {
  // Traversing the NameTree
  UString key;
  for (DictIterator i = dests.GetIterator(); i.HasNext(); i.Next())
     i.Key().GetAsPDFText(key); // ...
}

static Create(doc, name)

Retrieves the NameTree inside the ‘/Root/Names’ dictionary with the specified key name, or creates it if it does not exist.

Parameters:

• doc (SDFDoc) –

  • The document in which the name tree is created.

• name (string) –

  • The name of the NameTree to create.

Return type:

NameTree

Returns:

The newly created NameTree for the doc or an existing tree with the same key name.

Notes: although it is possible to create a name tree anywhere in the document the convention is that all trees are located under ‘/Root/Names’ dictionary.

Erase(args)

Overload 1:

Removes the specified object from the tree. Does nothing if no object with that name exists.

Parameters:

• key (UChar) – data buffer representing the key of the entry to be removed.

• key_sz (int) – The size (in bytes) of the key.

Overload 2:

Removes the NameTree entry pointed by the iterator.

Parameters:

pos (DictIterator) – ditionary iterator object that points to the NameTree entry to be removed.

static Find(doc, name)

Retrieves a name tree, with the given key name, from the ‘/Root/Names’ dictionary of the doc.

Parameters:

• doc (SDFDoc) –

  • The document in which to search for the name.

• name (string) –

  • The name of the name tree to find.

Return type:

NameTree

Returns:

The requested NameTree. If the requested NameTree exists NameTree.IsValid() will return true, and false otherwise.

GetIterator(args)

Overload 1:

Search for the specified key in the NameTree.

Return type:

NameTreeIterator

Returns:

If the key is present the function returns a NameTreeIterator the points to the given Key/Value pair. If the key is not found the function returns End() (a non-valid) iterator.

Parameters:

• key (UChar) – data buffer representing the key to be found.

• key_sz (int) – The size (in bytes) of the key.

DictIterator i = dests.Find("MyKey", 5);
if (i.HasNext()) {
  UString key;
  i.GetKey().GetAsPDFText(key); // ...
  cout < "Value: " < i.GetValue().GetType() < endl;
}

Overload 2:

Return type:

NameTreeIterator

Returns:

an iterator that addresses the first element in the NameTree. The iterator can be used to traverse all entries stored in the NameTree.

UString key;
for (NameTreeIterator i = dests.GetIterator(); i.HasNext(); i.Next()) {
  i.GetKey().GetAsPDFText(key); // ...
}

GetSDFObj()

Return type:

Obj

Returns:

the object to the underlying SDF/Cos object. If the NameTree.IsValid() returns false the SDF/Cos object is NULL.

GetValue(key, key_sz)

Search the NameTree for a given key.

Parameters:

• key (UChar) –

  • a key to search for in the dictionary

• key_sz (int) –

  • the buffer size used to store the key.

Return type:

Obj

Returns:

null if the tree does not contain the specified key, otherwise return the corresponding value.

IsValid()

Return type:

boolean

Returns:

whether this is a valid (non-null) NameTree. If the function returns false the underlying SDF/Cos object is null and the NameTree object should be treated as null as well.

Put(key, key_sz, value)

Puts a new entry in the name tree. If an entry with this key is already in the tree, it is replaced.

Parameters:

• key (UChar) – data buffer representing the key of the new entry.

• key_sz (int) – The size (in bytes) of the key.

• value (Obj) – the value associated with the key. It can be any SDF::Obj.

property thisown

The membership flag

apryse_sdk.NameTree_Create(doc, name)

Retrieves the NameTree inside the ‘/Root/Names’ dictionary with the specified key name, or creates it if it does not exist.

Parameters:

• doc (SDFDoc) –

  • The document in which the name tree is created.

• name (string) –

  • The name of the NameTree to create.

Return type:

NameTree

Returns:

The newly created NameTree for the doc or an existing tree with the same key name.

Notes: although it is possible to create a name tree anywhere in the document the convention is that all trees are located under ‘/Root/Names’ dictionary.

apryse_sdk.NameTree_Find(doc, name)

Retrieves a name tree, with the given key name, from the ‘/Root/Names’ dictionary of the doc.

Parameters:

• doc (SDFDoc) –

  • The document in which to search for the name.

• name (string) –

  • The name of the name tree to find.

Return type:

NameTree

Returns:

The requested NameTree. If the requested NameTree exists NameTree.IsValid() will return true, and false otherwise.

class apryse_sdk.NumberTree(args)

Bases: object

A NumberTree is a common data structure in PDF. See section 3.8.6 ‘Number Trees’ in PDF Reference Manual for more details.

A number tree serves a similar purpose to a dictionary - associating keys and values - but by different means. NumberTrees allow efficient storage of very large association collections (number/Obj maps). A NumberTree can have many more entries than a SDF/Cos dictionary can.

Sample code:

PDFDoc doc("../Data/test.pdf");
NumberTree labels(doc.GetRoot().Get("PageLabels").Value());
if (labels.IsValid()) {
  // Traversing the NumberTree
  for (NumberTreeIterator i = labels.GetIterator(); i.HasNext(); i.Next())
      cout < "Key: " < i.Key().GetNumber() < endl;
}

Erase(args)

Overload 1:

Removes the specified object from the tree. Does nothing if no object with that number exists.

Parameters:

key (int) – A number representing the key of the entry to be removed.

Overload 2:

Removes the NumberTree entry pointed by the iterator.

Parameters:

pos (DictIterator) – dictionary iterator object that points to the NumberTree entry to be removed

GetIterator(args)

Overload 1:

Search for the specified key in the NumberTree.

Return type:

NumberTreeIterator

Returns:

If the key is present the function returns a NumberTreeIterator the points to the given Key/Value pair. If the key is not found the function returns End() (a non-valid) iterator.

Parameters:

key (int) – the number representing the key to be found.

Sample code:

NumberTreeIterator i = dests.Find(5); if (i.HasNext()) {

cout << “Key: “ << i.GetKey()->GetNumber() << endl; cout << “Value: “ << i.GetValue()->GetType() << endl;

}

Overload 2:

Return type:

NumberTreeIterator

Returns:

an iterator to the first key/value pair (i.e. NNTreeData) in the document. You can use the Next method on the returned iterator to traverse all entries stored under the NumberTree.

Sample code:

for (NumberTreeIterator i = dests.GetIterator(); i.HasNext(); i.Next())

cout << “Key: “ << i.GetKey().GetNumber() << endl;

GetSDFObj()

Return type:

Obj

Returns:

the object to the underlying SDF/Cos object. If the NumberTree.IsValid() returns false the SDF/Cos object is NULL.

GetValue(key)

IsValid()

Return type:

boolean

Returns:

whether this is a valid (non-null) NumberTree. If the function returns false the underlying SDF/Cos object is null and the NumberTree object should be treated as null as well.

Put(key, value)

Puts a new entry in the name tree. If an entry with this number is already in the tree, it is replaced.

Parameters:

• key (int) – A number representing the key of the new entry.

• value (Obj) – the value associated with the key. It can be any SDF::Obj.

property thisown

The membership flag

class apryse_sdk.OCMD(args)

Bases: object

The OCMD object represents an Optional Content Membership Dictionary (OCMD) that allows the visibility of optional content to depend on the states in a set of optional-content groups (OCG::Group). The object directly corresponds to the OCMD dictionary (Section 4.10.1 ‘Optional Content Groups’ in PDF Reference).

An OCMD collects a set of OCGs. It sets a visibility policy, so that content in the member groups is visible only when all groups are ON or OFF, or when any of the groups is ON or OFF. This makes it possible to set up complex dependencies among groups. For example, an object can be visible only if some other conditions are met (such as if another layer is visible).

static Create(doc, ocgs, vis_policy)

Creates a new optional-content membership dictionary (OCMD) object in the given document for the given groups and visibility policy.

Parameters:

• doc (PDFDoc) – The document in which the new OCMD will be created.

• ocgs (Obj) – An array of optional-content groups (OCGs) to be members of the dictionary.

• policy – The visibility policy that determines the visibility of content with respect to the ON-OFF state of OCGs listed in the dictionary.

Return type:

OCMD

Returns:

The newly created OCG::OCMD object.

GetOCGs()

Returns the optional-content groups listed under ‘OCGs’ entry in the object dictionary.

Return type:

Obj

Returns:

A dictionary (for a single OCG::Group object), an SDF::Obj array (for multiple OCG::Group objects) or NULL (for an empty OCMD).

GetSDFObj()

Return type:

Obj

Returns:

Pointer to the underlying SDF/Cos object.

GetVisibilityExpression()

Return type:

Obj

Returns:

If the PDOCMD has a visibility expression entry, return the SDF::Obj array object representing the expression, otherwise returns NULL.

GetVisibilityPolicy()

Returns the optional-content membership dictionary’s visibility policy, which determines the visibility of content with respect to the ON-OFF state of OCGs listed in the dictionary.

Return type:

int

Returns:

The visibility policy.

IsCurrentlyVisible(context)

Return type:

boolean

Returns:

true if content tagged with this OCMD is visible in the given context, false if it is hidden.

Based on the optional-content groups listed in the dictionary, the current ON-OFF state of those groups within the specified context, and the dictionary’s visibility policy, test whether the content tagged with this dictionary would be visible.

Parameters:

context (Context) – The context in which the visibility of content is tested.

IsValid()

Return type:

boolean

Returns:

True if this is a valid (non-null) OCMD, false otherwise.

SetVisibilityPolicy(vis_policy)

Sets the optional-content membership dictionary’s visibility policy, which determines the visibility of content with respect to the ON-OFF state of OCGs listed in the dictionary.

Parameters:

vis_policy (int) – New visibility policy.

e_AllOff = 3

visible only if all of the entries in OCGs are OFF.

e_AllOn = 0

visible only if all of the entries in OCGs are ON.

e_AnyOff = 2

visible if any of the entries in OCGs are OFF.

e_AnyOn = 1

visible if any of the entries in OCGs are ON.

property mp_obj

property thisown

The membership flag

apryse_sdk.OCMD_Create(doc, ocgs, vis_policy)

Creates a new optional-content membership dictionary (OCMD) object in the given document for the given groups and visibility policy.

Parameters:

• doc (PDFDoc) – The document in which the new OCMD will be created.

• ocgs (Obj) – An array of optional-content groups (OCGs) to be members of the dictionary.

• policy – The visibility policy that determines the visibility of content with respect to the ON-OFF state of OCGs listed in the dictionary.

Return type:

OCMD

Returns:

The newly created OCG::OCMD object.

class apryse_sdk.OCRModule

Bases: object

The class OCRModule. static interface to PDFTron SDKs OCR functionality

static ApplyOCRJsonToPDF(dst, json)

Add hidden text layer to a PDF consisting of raster image(s).

Parameters:

• dst (PDFDoc) – – The source and destination document.

• json (string) – – JSON representing OCR results.

static ApplyOCRXmlToPDF(dst, xml)

Add hidden text layer to a PDF consisting of raster image(s).

Parameters:

• dst (PDFDoc) – – The source and destination document.

• xml (string) – – XML representing OCR results.

static GetOCRJsonFromImage(dst, src, options)

Perform OCR on an image and return resulting JSON string. Side effect: source image is converted to PDF and stored in the destination document. The box is a summary for a text fragment bounding box (leftmost x, bottommost y, width, height) The box coordinates are in units of points (1/72 of an inch), with the origin at the top left, and larger x and y coordinates representing further right and down, respectively

Parameters:

• dst (PDFDoc) – – The destination document.

• src (string) – – The path to the input image.

• options (OCROptions) – – OCR options (optional).

Return type:

string

Returns:

JSON string representing OCR results.

static GetOCRJsonFromPDF(src, options)

Perform OCR on raster images within a PDF and return resulting JSON string. The box is a summary for a text fragment bounding box (leftmost x, bottommost y, width, height) The box coordinates are in units of points (1/72 of an inch), with the origin at the top left, and larger x and y coordinates representing further right and down, respectively

Parameters:

• src (PDFDoc) – – The source document.

• options (OCROptions) – – OCR options (optional).

Return type:

string

Returns:

JSON string representing OCR results.

static GetOCRXmlFromImage(dst, src, options)

Perform OCR on an image and return resulting XML string. Side effect: source image is converted to PDF and stored in the destination document. The box is a summary for a text fragment bounding box (leftmost x, bottommost y, width, height) The box coordinates are in units of points (1/72 of an inch), with the origin at the top left, and larger x and y coordinates representing further right and down, respectively

Parameters:

• dst (PDFDoc) – – The destination document.

• src (string) – – The path to the input image.

• options (OCROptions) – – OCR options (optional).

Return type:

string

Returns:

XML string representing OCR results.

static GetOCRXmlFromPDF(src, options)

Perform OCR on raster images within a PDF and return resulting XML string. The box is a summary for a text fragment bounding box (leftmost x, bottommost y, width, height) The box coordinates are in units of points (1/72 of an inch), with the origin at the top left, and larger x and y coordinates representing further right and down, respectively

Parameters:

• src (PDFDoc) – – The source document.

• options (OCROptions) – – OCR options (optional).

Return type:

string

Returns:

XML string representing OCR results.

static ImageToPDF(dst, src, options)

Convert an image to a PDF with searchable text.

Parameters:

• dst (PDFDoc) – – The destination document.

• src (string) – – The path to the input image.

• options (OCROptions) – – OCR options (optional).

static IsIRISModuleAvailable()

Find out whether the IRIS OCR module is available.

Return type:

boolean

Returns:

returns true if the IRIS ocr module has been located.

static IsModuleAvailable()

Find out whether the OCR module is available (and licensed).

Return type:

boolean

Returns:

returns true if OCR operations can be performed.

static ProcessPDF(dst, options)

Add searchable and selectable text to raster images within a PDF.

Parameters:

• dst (PDFDoc) – – The source and destination document.

• options (OCROptions) – – OCR options (optional).

property thisown

The membership flag

apryse_sdk.OCRModule_ApplyOCRJsonToPDF(dst, json)

Add hidden text layer to a PDF consisting of raster image(s).

Parameters:

• dst (PDFDoc) – – The source and destination document.

• json (string) – – JSON representing OCR results.

apryse_sdk.OCRModule_ApplyOCRXmlToPDF(dst, xml)

Add hidden text layer to a PDF consisting of raster image(s).

Parameters:

• dst (PDFDoc) – – The source and destination document.

• xml (string) – – XML representing OCR results.

apryse_sdk.OCRModule_GetOCRJsonFromImage(dst, src, options)

Perform OCR on an image and return resulting JSON string. Side effect: source image is converted to PDF and stored in the destination document. The box is a summary for a text fragment bounding box (leftmost x, bottommost y, width, height) The box coordinates are in units of points (1/72 of an inch), with the origin at the top left, and larger x and y coordinates representing further right and down, respectively

Parameters:

• dst (PDFDoc) – – The destination document.

• src (string) – – The path to the input image.

• options (OCROptions) – – OCR options (optional).

Return type:

string

Returns:

JSON string representing OCR results.

apryse_sdk.OCRModule_GetOCRJsonFromPDF(src, options)

Perform OCR on raster images within a PDF and return resulting JSON string. The box is a summary for a text fragment bounding box (leftmost x, bottommost y, width, height) The box coordinates are in units of points (1/72 of an inch), with the origin at the top left, and larger x and y coordinates representing further right and down, respectively

Parameters:

• src (PDFDoc) – – The source document.

• options (OCROptions) – – OCR options (optional).

Return type:

string

Returns:

JSON string representing OCR results.

apryse_sdk.OCRModule_GetOCRXmlFromImage(dst, src, options)

Perform OCR on an image and return resulting XML string. Side effect: source image is converted to PDF and stored in the destination document. The box is a summary for a text fragment bounding box (leftmost x, bottommost y, width, height) The box coordinates are in units of points (1/72 of an inch), with the origin at the top left, and larger x and y coordinates representing further right and down, respectively

Parameters:

• dst (PDFDoc) – – The destination document.

• src (string) – – The path to the input image.

• options (OCROptions) – – OCR options (optional).

Return type:

string

Returns:

XML string representing OCR results.

apryse_sdk.OCRModule_GetOCRXmlFromPDF(src, options)

Perform OCR on raster images within a PDF and return resulting XML string. The box is a summary for a text fragment bounding box (leftmost x, bottommost y, width, height) The box coordinates are in units of points (1/72 of an inch), with the origin at the top left, and larger x and y coordinates representing further right and down, respectively

Parameters:

• src (PDFDoc) – – The source document.

• options (OCROptions) – – OCR options (optional).

Return type:

string

Returns:

XML string representing OCR results.

apryse_sdk.OCRModule_ImageToPDF(dst, src, options)

Convert an image to a PDF with searchable text.

Parameters:

• dst (PDFDoc) – – The destination document.

• src (string) – – The path to the input image.

• options (OCROptions) – – OCR options (optional).

apryse_sdk.OCRModule_IsIRISModuleAvailable()

Find out whether the IRIS OCR module is available.

Return type:

boolean

Returns:

returns true if the IRIS ocr module has been located.

apryse_sdk.OCRModule_IsModuleAvailable()

Find out whether the OCR module is available (and licensed).

Return type:

boolean

Returns:

returns true if OCR operations can be performed.

apryse_sdk.OCRModule_ProcessPDF(dst, options)

Add searchable and selectable text to raster images within a PDF.

Parameters:

• dst (PDFDoc) – – The source and destination document.

• options (OCROptions) – – OCR options (optional).

class apryse_sdk.OCROptions

Bases: object

AddDPI(dpi)

Knowing proper image resolution is important, as it enables the OCR engine to translate pixel heights of characters to their respective font sizes. We do our best to retrieve resolution information from the input’s metadata, however it occasionally can be corrupt or missing. Hence we allow manual override of source’s resolution, which supersedes any metadata found (both explicit as in image metadata and implicit as in PDF).

Parameters:

dpi: – image resolution

Return type:

OCROptions

Returns:

this object, for call chaining

AddIgnoreZonesForPage(regions, page_num)

Adds a collection of ignorable regions for the given page, an optional list of page areas not to be included in analysis

Parameters:

• regions: – the zones to be added to the ignore list

• page_num: – the page number the added regions belong to

Return type:

OCROptions

Returns:

this object, for call chaining

AddLang(lang)

Adds a language to the list of to be considered when processing this document

Parameters:

lang: – the new language to be added to the language list

Return type:

OCROptions

Returns:

this object, for call chaining

AddTextZonesForPage(regions, page_num)

Adds a collection of text regions of interest for the given page, an optional list of known text zones that will be used to improve OCR quality

Parameters:

• regions: – the zones to be added to the text region list

• page_num: – the page number the added regions belong to

Return type:

OCROptions

Returns:

this object, for call chaining

GetAutoRotate()

Gets the value AutoRotate from the options object Default value is false. Setting to true will deskew the image before conducting OCR.

Return type:

boolean

Returns:

a bool, the current value for AutoRotate.

GetInternalObj()

GetOCREngine()

Gets the value OCREngine from the options object Backend engine to use for OCR processing. Options include ‘default’, ‘any’, or ‘iris’. Chosen module must be present and correctly licensed.

Return type:

string

Returns:

a string, the current value for OCREngine.

SetAutoRotate(value)

Sets the value for AutoRotate in the options object Default value is false. Setting to true will deskew the image before conducting OCR.

Parameters:

value: – the new value for AutoRotate

Return type:

OCROptions

Returns:

this object, for call chaining

SetIgnoreExistingText(value)

Sets the value for IgnoreExistingText in the options object Default value is false, so that areas with existing text will be automatically skipped during OCR. Setting to true probably only makes sense when used with GetOCRJson/XML, as pre-existing text might end up being duplicated in the document when used with ImageToPDF and ProcessPDF.

Parameters:

value: – the new value for IgnoreExistingText

Return type:

OCROptions

Returns:

this object, for call chaining

SetOCREngine(value)

Sets the value for OCREngine in the options object Backend engine to use for OCR processing. Options include ‘default’, ‘any’, or ‘iris’. Chosen module must be present and correctly licensed.

Parameters:

value: – the new value for OCREngine

Return type:

OCROptions

Returns:

this object, for call chaining

SetUsePDFPageCoords(value)

Sets the value for UsePDFPageCoords in the options object Sets origin of the coordinate system for input/output

Parameters:

value: – If true, sets origin of the coordinate system for input/output to the bottom left corner and reverses the direction of y-coordinate axis from downward to upward, otherwise top left corner is used as the origin and the y-coordinate axis direction is downward

Return type:

OCROptions

Returns:

this object, for call chaining

property thisown

The membership flag

class apryse_sdk.Obj(args)

Bases: object

Obj is a concrete class for all SDF/Cos objects. Obj hierarchy implements the composite design pattern. As a result, you can invoke a member function of any ‘derived’ object through Obj interface. If the member function is not supported (e.g. if you invoke Obj::GetNumber() on a boolean object) an Exception will be thrown.

You can use GetType() or obl.Is???() member functions to find out type-information at run time, however most of the time the type can be inferred from the PDF specification. Therefore when you call Doc::GetTrailer() you can assume that returned object is a dictionary. If there is any ambiguity use Is???() methods.

Objects can’t be shared across documents, however you can use Doc::ImportObj() to copy objects from one document to another.

Objects can be shared within a document provided that they are created as indirect. Indirect objects are the ones that are referenced in cross-reference table. To create an object as indirect use doc.CreateIndirect???() (where ? is the Object type).

static CreateInternal(impl)

Erase(args)

Overload 1:

Removes an element in the dictionary that matches the given key.

Parameters:

key (string) – A string representing the key value of the element to remove.

Raises:

An Exception is thrown if this is not a dictionary or a stream.

Overload 2:

Removes an element in the dictionary from specified position.

Parameters:

pos (DictIterator) – A dictionary iterator indicating the position of the element to remove.

Raises:

An Exception is thrown if this is not a dictionary or a stream.

EraseAt(pos)

Checks whether the position is within the array bounds and then removes it from the array and moves each subsequent element to the slot with the next smaller index and decrements the arrays length by 1.

Parameters:

pos (int) – The index for the array member to remove. Array indexes start at 0.

Raises:

An Exception is thrown if this is not an Obj::Type::e_array

Find(key)

Search the dictionary for a given key.

Parameters:

key (string) –

• a key to search for in the dictionary

Return type:

DictIterator

Returns:

The iterator to the matching key/value pair or invalid iterator (i.e. itr.HasNext()==fase) if the if the dictionary does not contain the given key.

Notes: A dictionary entry whose value is Obj::Null is equivalent to an absent entry. :raises: Exception is thrown if this is not a dictionary or a stream

Sample code used to search a dictionary for a given key:

 DictIterator itr = info_dict.Find("Info");
 if (itr.HasNext()) {
   Obj info = itr.Value();
   if (info.IsDict())
     info.PutString("Producer", "PDFTron PDFNet SDK");
}

FindObj(key)

Search the dictionary for a given key.

Parameters:

key (string) –

• a key to search for in the dictionary

Return type:

Obj

Returns:

NULL if the dictionary does not contain the specified key. Otherwise return the corresponding value.

Notes: A dictionary entry whose value is Obj::Null is equivalent to an absent entry. :raises: Exception is thrown if this is not a dictionary or a stream

Get(key)

Search the dictionary for a given key and throw an exception if the key is not found.

Parameters:

key (string) –

• a key to search for in the dictionary

Return type:

DictIterator

Returns:

Obj::Null object if the value matching specified key is a Obj::Null object. otherwise return the iterator to the matching key/value pair.

Raises:

An Exception is thrown if the dictionary does not contain the specified key.

Raises:

An Exception is thrown if this is not a Obj::Type::e_dict or a stream.

GetAsPDFText()

Convert the SDF/Cos String object to ‘PDF Text String’ (a Unicode string).

PDF Text Strings are not used to represent page content, however they are used in text annotations, bookmark names, article names, document information etc. These strings are encoded in either PDFDocEncoding or Unicode character encoding. For more information on PDF Text Strings, please refer to section 3.8.1 ‘Text Strings’ in PDF Reference.

Notes: Not all SDF/Cos String objects are used to represent ‘PDF Text’. PDF Reference indicates (on a case by case basis ) where an SDF/Cos String object can be used as ‘PDF Text’.

Raises:

An Exception is thrown if this is not a Obj::Type::e_string.

GetAt(index)

Parameters:

index (int) –

• The array element to obtain. The first element in an array has an index of zero.

Raises:

throws an Exception if index is outside the array bounds.

Raises:

An Exception is thrown if this is not an Obj::Type::e_array.

GetBool()

Return type:

boolean

Returns:

bool value if this is Bool.

Raises:

Exception is thrown if the object is not Obj::Type::e_bool

GetBuffer()

Return type:

std::vector< unsigned char,std::allocator< unsigned char > >

Returns:

a pointer to the string buffer. Please note that the string may not be NULL terminated and that it may not be represented in ASCII or Unicode encoding. For more information on SDF/Cos String objects, please refer to section 3.2.3 ‘String Objects’ in PDF Reference Manual.

Notes: if SDF/Cos String object is represented as ‘PDF Text’ (Section 3.8.1 ‘Text Strings’ in PDF Reference) you can use GetAsPDFText method to obtain Unicode representation of the string.

use Size() member function in order to obtain the number of bytes in string buffer.

Raises:

Exception is thrown if this is not a Obj::Type::e_string.

GetDecodedStream()

Return type:

Filter

Returns:

• A filter to the decoded stream

Raises:

An Exception is thrown if this is not a Obj::Type::e_stream

GetDictIterator()

Return type:

DictIterator

Returns:

an iterator that addresses the first element in the dictionary.

Raises:

An Exception is thrown if this is not a dictionary object (Dict).

Sample code used to traverse all entries in the dictionary:

DictIterator itr = dict.GetDictIterator();
while (itr.HasNext()) {
    Obj key = itr.Key();
    Obj value = itr.Value();
    // ...
    itr.Next()
 }

GetDoc()

Return type:

SDFDoc

Returns:

the document to which this object belongs.

Notes: this method can be invoked on any Obj.

GetGenNum()

Return type:

int

Returns:

generation number. If this is not an Indirect object, generation number of a containing indirect object is returned.

Notes: this method can be invoked on any Obj.

GetHandleInternal()

GetName()

Return type:

string

Returns:

string representing the Name object.

Raises:

An Exception is thrown if this is not a Obj::Type::e_name

GetNumber()

Return type:

double

Returns:

value, if this is Number.

Raises:

An Exception is thrown if the object is not a Obj::Type::e_number

GetObjNum()

Return type:

int

Returns:

object number. If this is not an Indirect object, object number of a containing indirect object is returned.

Notes: this method can be invoked on any Obj.

GetOffset()

Return type:

int

Returns:

object offset from the beginning of the file. If this is not an Indirect object, offset of a containing indirect object is returned.

Notes: this method can be invoked on any Obj.

GetRawBuffer()

Return type:

std::vector< unsigned char,std::allocator< unsigned char > >

Returns:

a vector containing the encrypted string buffer.

Notes: Similar in behaviour to GetBuffer except that no decryption is done. If the file is not encrypted the result should be the same as GetBuffer

Raises:

Exception is thrown if this is not a Obj::Type::e_string.

GetRawStream(decrypt)

Parameters:

decrypt (boolean) –

• If true decrypt the stream if the stream is encrypted.

Return type:

Filter

Returns:

• A filter to the encoded stream

Raises:

An Exception is thrown if this is not a Obj::Type::e_stream

GetRawStreamLength()

Return type:

int

Returns:

the length of the raw/encoded stream equal to the Length parameter

Raises:

An Exception is thrown if this is not a Obj::Type::e_stream

GetType()

Return type:

int

Returns:

the object type.

Notes: this method can be invoked on any Obj.

Insert(pos, obj)

Inserts an existing Obj in this array.

Parameters:

• pos (int) –

  • The location in the array to insert the object . The object is inserted

  before the specified location. The first element in an array has a pos of

  zero. If pos >= Array->Length(), appends obj to array.

• obj (Obj) – The value to be inserted into the dictionary. If ‘obj’ is indirect (i.e. is a shared) object it will be inserted by reference, otherwise the object will be cloned and then inserted.

Return type:

Obj

Returns:

A newly inserted object.

Raises:

An Exception is thrown if this is not an Obj::Type::e_array

InsertArray(pos)

Inserts an Obj::Type::e_array object in the array.

Return type:

Obj

Returns:

A newly created array object.

Parameters:

pos (int) –

• The location in the array to insert the object . The object is inserted

before the specified location. The first element in an array has a pos of

zero. If pos >= Array->Length(), appends obj to array.

Raises:

An Exception is thrown if this is not an Obj::Type::e_array

InsertBool(pos, value)

Inserts an Obj::Type::e_bool object in the array.

Return type:

Obj

Returns:

A newly created boolean object.

Parameters:

• pos (int) –

  • The location in the array to insert the object . The object is inserted

  before the specified location. The first element in an array has a pos of

  zero. If pos >= Array->Length(), appends obj to array.

• value (boolean) – The value of the Obj::Type::e_bool object to be inserted.

Raises:

An Exception is thrown if this is not an Obj::Type::e_array

InsertDict(pos)

Inserts an Obj::Type::e_dict object in the array.

Return type:

Obj

Returns:

A newly created dictionary object.

Parameters:

pos (int) –

• The location in the array to insert the object . The object is inserted

before the specified location. The first element in an array has a pos of

zero. If pos >= Array->Length(), appends obj to array.

Raises:

An Exception is thrown if this is not an Obj::Type::e_array

InsertMatrix(pos, value)

Inserts an array of 6 numbers in this array.

Parameters:

• pos (int) –

  • The location in the array to insert the object . The object is inserted

  before the specified location. The first element in an array has a pos of

  zero. If pos >= Array->Length(), appends obj to array.

• value (Matrix2D) –

  • A matrix used to set the values in an array of six numbers.

  The resulting array will be then inserted in this array.

Return type:

Obj

Returns:

A newly created array object.

Raises:

An Exception is thrown if this is not an Obj::Type::e_array

InsertName(pos, name)

Inserts an Obj::Type::e_name object in the array.

Return type:

Obj

Returns:

A newly created name object.

Parameters:

• pos (int) –

  • The location in the array to insert the object . The object is inserted

  before the specified location. The first element in an array has a pos of

  zero. If pos >= Array->Length(), appends obj to array.

• name (string) – The value of the Obj::Type::e_name object to be inserted.

Raises:

An Exception is thrown if this is not an Obj::Type::e_array

InsertNull(pos)

Inserts an Obj::Type::e_null object in the array.

Return type:

Obj

Returns:

A newly created null object.

Parameters:

pos (int) –

• The location in the array to insert the object . The object is inserted

before the specified location. The first element in an array has a pos of

zero. If pos >= Array->Length(), appends obj to array.

Raises:

An Exception is thrown if this is not an Obj::Type::e_array

InsertNumber(pos, value)

Inserts an Obj::Type::e_number object in the array.

Return type:

Obj

Returns:

A newly created number object.

Parameters:

• pos (int) –

  • The location in the array to insert the object . The object is inserted

  before the specified location. The first element in an array has a pos of

  zero. If pos >= Array->Length(), appends obj to array.

• value (double) – The value of the Obj::Type::e_number object to be inserted.

Raises:

An Exception is thrown if this is not an Obj::Type::e_array

InsertRect(pos, x1, y1, x2, y2)

Inserts an array of 4 numbers in this array.

Parameters:

• pos (int) –

  • The location in the array to insert the object . The object is inserted

  before the specified location. The first element in an array has a pos of

  zero. If pos >= Array->Length(), appends obj to array.

• x1 (double) – The bottom left x value of the rect to be inserted

• y1 (double) – The bottom left y value of the rect to be inserted

• x2 (double) – The top right x value of the rect to be inserted

• y2 (double) – The top right y value of the rect to be inserted

Return type:

Obj

Returns:

A newly created array object.

Raises:

An Exception is thrown if this is not an Obj::Type::e_array

InsertString(args)

Overload 1:

Inserts an Obj::Type::e_string object in the array.

Return type:

Obj

Returns:

A newly created string object.

Parameters:

• pos (int) –

  • The location in the array to insert the object . The object is inserted

  before the specified location. The first element in an array has a pos of

  zero. If pos >= Array->Length(), appends obj to array.

• value (string) – The value of the Obj::Type::e_string object to be inserted.

Raises:

An Exception is thrown if this is not an Obj::Type::e_array

Overload 2:

Inserts an Obj::Type::e_string object in the array.

Return type:

Obj

Returns:

A newly created string object.

Parameters:

• pos (int) –

  • The location in the array to insert the object . The object is inserted

  before the specified location. The first element in an array has a pos of

  zero. If pos >= Array->Length(), appends obj to array.

• value (string) – The buffer used to set the value of the Obj::Type::e_string object to be inserted.

• size (int) – The number of bytes to copy from the ‘value’ buffer parameter.

Raises:

An Exception is thrown if this is not an Obj::Type::e_array

InsertText(pos, value)

Inserts an Obj::Type::e_string object in the array.

Return type:

Obj

Returns:

A newly created string object.

Parameters:

• pos (int) –

  • The location in the array to insert the object . The object is inserted

  before the specified location. The first element in an array has a pos of

  zero. If pos >= Array->Length(), appends obj to array.

• value (string) – The value of the Obj::Type::e_string object to be inserted.

Notes: InsertText will create the string object as a ‘PDF Text’ object. :raises: An Exception is thrown if this is not an Obj::Type::e_array

IsArray()

Return type:

boolean

Returns:

true if this is an Array, false otherwise.

Notes: this method can be invoked on any Obj.

IsBool()

Return type:

boolean

Returns:

true if this is a Bool object, false otherwise.

Notes: this method can be invoked on any Obj.

IsContainer()

Return type:

boolean

Returns:

true if this is a Container (a dictionary, array, or a stream), false otherwise.

Notes: this method can be invoked on any Obj.

IsDict()

Return type:

boolean

Returns:

true if this is a dictionary (i.e. Dict), false otherwise.

Notes: this method can be invoked on any Obj.

IsEqual(to)

Return type:

boolean

Returns:

true if two Obj’s point to the same object. This method does not compare object content. For this operation use IsEqualValue() instead.

Parameters:

to (Obj) –

• Obj to compare to

IsFree()

Return type:

boolean

Returns:

true if the object is in use or is marked as free.

Notes: this method can be invoked on any Obj.

IsIndirect()

Return type:

boolean

Returns:

true if this is Indirect object (i.e. object referenced in the cross-reference table), false otherwise.

Notes: this method can be invoked on any Obj.

IsLoaded()

Return type:

boolean

Returns:

true if the object is loaded in memory.

Notes: this method can be invoked on any Obj.

IsMarked()

Return type:

boolean

Returns:

true if the object is marked.

Notes: this method can be invoked on any Obj.

IsName()

Return type:

boolean

Returns:

true if this is Name, false otherwise.

Notes: this method can be invoked on any Obj.

IsNull()

Return type:

boolean

Returns:

true if this is a Null object, false otherwise.

Notes: this method can be invoked on any Obj.

IsNumber()

Return type:

boolean

Returns:

true if this is a Number object, false otherwise.

Notes: this method can be invoked on any Obj.

IsStream()

Return type:

boolean

Returns:

true if this is a Stream, false otherwise.

Notes: this method can be invoked on any Obj.

IsString()

Return type:

boolean

Returns:

true if this is a Str (String) object, false otherwise.

Notes: this method can be invoked on any Obj.

IsValid()

Return type:

boolean

Returns:

true if this is a valid object, false otherwise. If the function returns false then the underlying SDF/Cos object is null or is not valid.

PushBack(obj)

Appends an existing Obj at the end of the array.

Parameters:

obj (Obj) – The value to be inserted into the dictionary. If ‘obj’ is indirect (i.e. is a shared) object it will be inserted by reference, otherwise the object will be cloned and then appended.

Return type:

Obj

Returns:

A newly appended object.

Raises:

An Exception is thrown if this is not an Obj::Type::e_array

PushBackArray()

Appends a new Obj::Type::e_array object at the end of the array.

Return type:

Obj

Returns:

The new array object.

Raises:

An Exception is thrown if this is not an Obj::Type::e_array

PushBackBool(value)

Appends a new Obj::Type::e_bool object at the end of the array.

Return type:

Obj

Returns:

The new boolean object.

Parameters:

value (boolean) –

• The value of the Obj::Type::e_bool object.

Raises:

An Exception is thrown if this is not an Obj::Type::e_array

PushBackDict()

Appends a new Obj::Type::e_dict object at the end of the array.

Return type:

Obj

Returns:

The new dictionary object.

Raises:

An Exception is thrown if this is not an Obj::Type::e_array

PushBackMatrix(value)

Appends an array of 6 numbers at the end of the array.

Parameters:

value (Matrix2D) –

• A matrix used to set the values in an array of six numbers.

The resulting array will be then inserted in this array.

Return type:

Obj

Returns:

A newly appended array object.

Raises:

An Exception is thrown if this is not an Obj::Type::e_array

PushBackName(name)

Appends a new Obj::Type::e_name object at the end of the array.

Return type:

Obj

Returns:

The new array object.

Parameters:

name (string) –

• The value of the Obj::Type::e_name object.

Raises:

An Exception is thrown if this is not an Obj::Type::e_array

PushBackNull()

Appends a new Obj::Type::e_null object at the end of the array.

Return type:

Obj

Returns:

The new null object.

Raises:

An Exception is thrown if this is not an Obj::Type::e_array

PushBackNumber(value)

Appends a new Obj::Type::e_number object at the end of the array.

Return type:

Obj

Returns:

The new number object.

Parameters:

value (double) –

• The value of the Obj::Type::e_number object.

Raises:

An Exception is thrown if this is not an Obj::Type::e_array

PushBackRect(x1, y1, x2, y2)

Appends an array of 4 numbers at the end of the array.

Parameters:

• x1 (double) – The bottom left x value of the rect to be inserted

• y1 (double) – The bottom left y value of the rect to be inserted

• x2 (double) – The top right x value of the rect to be inserted

• y2 (double) – The top right y value of the rect to be inserted

Return type:

Obj

Returns:

A newly appended array object.

Raises:

An Exception is thrown if this is not an Obj::Type::e_array

PushBackString(args)

Overload 1:

Appends a new Obj::Type::e_string object at the end of the array.

Return type:

Obj

Returns:

The new string object.

Parameters:

value (string) –

• The value of the Obj::Type::e_string object.

Raises:

An Exception is thrown if this is not an Obj::Type::e_array

Overload 2:

Appends a new Obj::Type::e_string object at the end of the array.

Return type:

Obj

Returns:

The new string object.

Parameters:

• value (string) – The buffer used to set the value of the Obj::Type::e_string object to be inserted.

• size (int) – The number of bytes to copy from the ‘value’ buffer parameter.

Raises:

An Exception is thrown if this is not an Obj::Type::e_array

PushBackText(value)

Appends a new Obj::Type::e_string object at the end of the array.

Return type:

Obj

Returns:

The new string object.

Parameters:

value (string) – The value of the Obj::Type::e_string object to be inserted.

Notes: InsertText will create the string object as a ‘PDF Text’ object. :raises: An Exception is thrown if this is not an Obj::Type::e_array

Put(key, obj)

Inserts a <key, Obj> pair in the dictionary.

Parameters:

• key (string) – The key of the value to set.

• obj (Obj) – The value to be inserted into the dictionary. If ‘obj’ is indirect (i.e. is a shared) object it will be inserted by reference, otherwise the object will be cloned and then inserted into the dictionary.

Return type:

Obj

Returns:

A newly inserted object.

Raises:

An Exception is thrown if this is not a dictionary or a stream object.

PutArray(key)

Inserts a <key, Obj::Type::e_array> pair in the dictionary.

Parameters:

key (string) – The key of the value to set.

Return type:

Obj

Returns:

A newly created array object.

Raises:

An Exception is thrown if this is not a dictionary or a stream object.

Notes: If a dictionary already contains an entry with the same key, the old entry will be deleted and all DictIterators to this entry will be invalidated.

PutBool(key, value)

Inserts a <key, Obj::Type::e_bool> pair in the dictionary.

Parameters:

• key (string) – The key of the value to set.

• value (boolean) – The value of the Obj::Type::e_bool object to be inserted into the dictionary.

Return type:

Obj

Returns:

A newly created boolean object.

Raises:

An Exception is thrown if this is not a dictionary or a stream object.

Notes: If a dictionary already contains an entry with the same key, the old entry will be deleted and all DictIterators to this entry will be invalidated.

PutDict(key)

Inserts a <key, Obj::Type::e_dict> pair in the dictionary.

Parameters:

key (string) – The key of the value to set.

Return type:

Obj

Returns:

A newly created dictionary.

Raises:

An Exception is thrown if this is not a dictionary or a stream object.

Notes: If a dictionary already contains an entry with the same key, the old entry will be deleted and all DictIterators to this entry will be invalidated.

PutMatrix(key, value)

Inserts a <key, [a,b,c,d,h,v]> pair in the dictionary.

Parameters:

• key (string) – The key of the value to set.

• value (Matrix2D) –

  • A matrix used to set the values in an array of six numbers.

  The resulting array will be inserted into the dictionary.

Return type:

Obj

Returns:

A newly created array object.

Raises:

An Exception is thrown if this is not a dictionary or a stream object.

Notes: If a dictionary already contains an entry with the same key, the old entry will be deleted and all DictIterators to this entry will be invalidated.

PutName(key, name)

Inserts a <key, Obj::Type::e_name> pair in the dictionary.

Parameters:

• key (string) – The key of the value to set.

• name (string) – The value of the Obj::Type::e_name object to be inserted into the dictionary.

Return type:

Obj

Returns:

A newly created name object.

Raises:

An Exception is thrown if this is not a dictionary or a stream object.

Notes: If a dictionary already contains an entry with the same key, the old entry will be deleted and all DictIterators to this entry will be invalidated.

PutNull(key)

Inserts a <key, Obj::Type::e_null> pair in the dictionary.

Parameters:

key (string) – The key of the value to set.

Raises:

An Exception is thrown if this is not a dictionary or a stream object.

Notes: The effect of calling this method is essentially the same as dict.Erase(key) .

PutNumber(key, value)

Inserts a <key, Obj::Type::e_number> pair in the dictionary.

Parameters:

• key (string) – The key of the value to set.

• value (double) – The value of the Obj::Type::e_number object to be inserted into the dictionary.

Return type:

Obj

Returns:

A newly created number object.

Raises:

An Exception is thrown if this is not a dictionary or a stream object.

Notes: If a dictionary already contains an entry with the same key, the old entry will be deleted and all DictIterators to this entry will be invalidated.

PutRect(key, x1, y1, x2, y2)

Inserts a <key, [x1,y1,x2,y2]> pair in the dictionary.

Parameters:

• key (string) – The key of the value to set.

• x1 (double) – The bottom left x value of the rect to be inserted

• y1 (double) – The bottom left y value of the rect to be inserted

• x2 (double) – The top right x value of the rect to be inserted

• y2 (double) – The top right y value of the rect to be inserted

Return type:

Obj

Returns:

A newly created array object.

Raises:

An Exception is thrown if this is not a dictionary or a stream object.

Notes: If a dictionary already contains an entry with the same key, the old entry will be deleted and all DictIterators to this entry will be invalidated.

PutString(args)

Overload 1:

Inserts a <key, Obj::Type::e_string> pair in the dictionary.

Parameters:

• key (string) – The key of the value to set.

• value (string) – The value of the Obj::Type::e_string object to be inserted into the dictionary.

Return type:

Obj

Returns:

A newly created string object.

Raises:

An Exception is thrown if this is not a dictionary or a stream object.

Notes: If a dictionary already contains an entry with the same key, the old entry will be deleted and all DictIterators to this entry will be invalidated.

Overload 2:

Inserts a <key, Obj::Type::e_string> pair in the dictionary.

Parameters:

• key (string) – The key of the value to set.

• value (string) – The buffer used to set the value of the Obj::Type::e_string object to be inserted into the dictionary.

• size (int) – The number of bytes to copy from the ‘value’ buffer parameter.

Return type:

Obj

Returns:

A newly created string object.

Raises:

An Exception is thrown if this is not a dictionary or a stream object.

Notes: If a dictionary already contains an entry with the same key, the old entry will be deleted and all DictIterators to this entry will be invalidated.

PutText(key, value)

Inserts a <key, Obj::Type::e_string> pair in the dictionary.

Parameters:

• key (string) – The key of the value to set.

• value (string) – The value of the Obj::Type::e_string object to be inserted into the dictionary.

Notes: PutText will create the string object as a ‘PDF Text’ object.

Return type:

Obj

Returns:

A newly created string object.

Raises:

An Exception is thrown if this is not a dictionary or a stream object.

If a dictionary already contains an entry with the same key, the old entry will be deleted and all DictIterators to this entry will be invalidated.

Rename(old_key, new_key)

Change the key value of a dictionary entry. The key can’t be renamed if another key with the same name already exists in the dictionary. In this case Rename returns false.

Parameters:

• old_key (string) – A string representing the key value to be changed.

• new_key (string) – A string representing the key value that the old key is changed into.

Raises:

An Exception is thrown if this is not a dictionary or a stream.

SetBool(b)

Parameters:

b (boolean) –

• bool value used to set Bool object.

Raises:

An Exception is thrown if this is not a Obj::Type::e_bool

SetMark(mark)

Set the object mark. Mark is a boolean value that can be associated with every indirect object. This is especially useful when an object graph should be traversed and an operation should be performed on each node only once.

Parameters:

mark (boolean) – boolean value that the object’s mark should be set to.

Notes: this method can be invoked on any Obj.

SetName(name)

Parameters:

name (string) –

• value used to set Name object.

Raises:

An Exception is thrown if this is not a Obj::Type::e_name

SetNumber(n)

Parameters:

n (double) –

• value used to set Number object.

Raises:

An Exception is thrown if this is not a Obj::Type::e_number

SetStreamData(args)

allows to replace the content stream with a new one without creating a new object

SetString(args)

Overload 1:

Sets the string object value.

Parameters:

• value (UChar) –

  • character buffer.

• size (int) –

  • the size of character buffer.

Raises:

An Exception is thrown if this is not a Obj::Type::e_string

Overload 2:

Sets the string object value.

Parameters:

str (string) –

• A Unicode string value.

Raises:

An Exception is thrown if this is not a Obj::Type::e_string

Size()

Return type:

int

Returns:

the ‘size’ of the object. The definition of ‘size’ depends on the object type. In particular:

• For a dictionary or a stream object, the method will return the number of key/value pairs in the dictionary.

• For an array object the method will return the number of Obj entries in the array.

• For a string object the method will return the number of bytes in the string buffer.

• For any other object the method will always return 1.

Notes: this method can be invoked on any Obj.

Write(stream)

The function writes the Obj to the output stream

Parameters:

stream (FilterWriter) –

• the input stream where the Obj will be written

Notes: this method can be invoked on any Obj.

e_array = 6

e_bool = 1

e_dict = 5

e_name = 3

e_null = 0

e_number = 2

e_stream = 7

e_string = 4

property mp_obj

property thisown

The membership flag

class apryse_sdk.ObjSet(args)

Bases: object

ObjSet is a lightweight container that can hold a collection of SDF objects.

CreateArray()

Create a new array object in this object set.

CreateBool(value)

Create a new boolean object in this object set.

Parameters:

value (boolean) – The boolean value of the object to create

CreateDict()

Create a new dictionary object in this object set.

CreateFromJson(value)

parses a json string to create either a Dictionary or an Array in ObjSet.

return the created object as Obj

CreateName(name)

Create a new name object in this object set.

Parameters:

name (string) – The name of the object to create

CreateNull()

Create a new null object in this object set.

CreateNumber(value)

Create a new number object in this object set.

Parameters:

value (double) – The numeric value of the number object to create.

CreateString(value)

Create a new string object in this object set. The unsigned string value of the string object to create.

Destroy()

Frees the native memory of the object.

property thisown

The membership flag

apryse_sdk.Obj_CreateInternal(impl)

class apryse_sdk.ObjectIdentifier(args)

Bases: object

This class represents an object identifier (OID), as defined by ITU and used in X.509.

Destroy()

GetRawValue()

Retrieves the value of the object identifier.

Return type:

std::vector< int,std::allocator< int > >

Returns:

the value of the object identifier, as a container of integer components.

e_RIPEMD160 = 12

e_RSA_encryption_PKCS1 = 13

e_SHA1 = 8

e_SHA256 = 9

e_SHA384 = 10

e_SHA512 = 11

e_commonName = 0

e_countryName = 2

e_localityName = 3

e_organizationName = 6

e_organizationalUnitName = 7

e_stateOrProvinceName = 4

e_streetAddress = 5

e_surname = 1

property m_impl

property thisown

The membership flag

class apryse_sdk.OfficeToPDFOptions

Bases: ConversionOptions

GetApplyPageBreaksToSheet()

Gets the value ApplyPageBreaksToSheet from the options object Whether we should split Excel workheets into pages so that the output resembles print output. If set to false (the default), Excel sheets will be placed one per page, except in the case where the sheets are very large

Return type:

boolean

Returns:

a bool, the current value for ApplyPageBreaksToSheet.

GetDisplayChangeTracking()

Gets the value DisplayChangeTracking from the options object If this option is true, will display office change tracking markup present in the document (i.e, red strikethrough of deleted content and underlining of new content). Otherwise displays the resolved document content, with no markup. Defaults to true.

Return type:

boolean

Returns:

a bool, the current value for DisplayChangeTracking.

GetDisplayHiddenText()

Gets the value DisplayHiddenText from the options object Display any hidden text that is present in the document (i.e., text that has been marked as ‘Hidden’ in the font style). By default, hidden text will not be displayed.

Return type:

boolean

Returns:

a bool, the current value for DisplayHiddenText.

GetExcelDefaultCellBorderWidth()

Gets the value ExcelDefaultCellBorderWidth from the options object Cell border width for table cells that would normally be drawn with no border. In units of points. Can be used to achieve a similar effect to the “show gridlines” display option within Microsoft Excel.

Return type:

double

Returns:

a double, the current value for ExcelDefaultCellBorderWidth.

GetExcelMaxAllowedCellCount()

Gets the value ExcelMaxAllowedCellCount from the options object Conversion will throw an exception if the number of cells in a Microsoft Excel document is above the set MaxAllowedCellCount. Used for early termination of resource intensive conversions. Setting this value to 250000 will allow the vast majority of Excel documents to convert without issue, while keeping RAM usage to a reasonable level. By default there is no limit to the number of allowed cells.

Return type:

int

Returns:

a UInt32, the current value for ExcelMaxAllowedCellCount.

GetHideTotalNumberOfPages()

Gets the value HideTotalNumberOfPages from the options object If the document has an element that displays the total number of pages and the total number of pages is unknown beforehand, remove those elements from the document.

Return type:

boolean

Returns:

a bool, the current value for HideTotalNumberOfPages.

GetLayoutResourcesPluginPath()

Gets the value LayoutResourcesPluginPath from the options object The path at which the pdftron-provided font resource plugin resides

Return type:

string

Returns:

a string, the current value for LayoutResourcesPluginPath.

GetLocale()

Gets the value Locale from the options object ISO 639-1 code of the locale to be applied during conversion. For example: ‘en-US’, ‘ar-SA’, ‘de-DE’, etc. Currently only applied during xls/xlsx conversions.

Return type:

string

Returns:

a string, the current value for Locale.

GetPassword()

Gets the value Password from the options object Password used to decrypt password-protected office documents.

Return type:

string

Returns:

a string, the current value for Password.

GetResourceDocPath()

Gets the value ResourceDocPath from the options object The path at which a .docx resource document resides

Return type:

string

Returns:

a string, the current value for ResourceDocPath.

GetSmartSubstitutionPluginPath()

Gets the value SmartSubstitutionPluginPath from the options object The path at which the pdftron-provided font resource plugin resides

Return type:

string

Returns:

a string, the current value for SmartSubstitutionPluginPath.

GetStructureTagLevel()

Gets the value StructureTagLevel from the options object Specifies the level of document structure tags to include in the PDF for accessibility purposes.

Return type:

int

Returns:

a StructureTagLevel, the current value for StructureTagLevel.

GetTemplateLeftDelimiter()

Gets the value TemplateLeftDelimiter from the options object Left delimiter for template tags. Defaults to ‘{{‘.

Return type:

string

Returns:

a string, the current value for TemplateLeftDelimiter.

GetTemplateParamsJson()

Gets the value TemplateParamsJson from the options object JSON string representing the data to be merged into a PDFTron office template. For a more featureful template API, see CreateOfficeTemplate.

Return type:

string

Returns:

a string, the current value for TemplateParamsJson.

GetTemplateRightDelimiter()

Gets the value TemplateRightDelimiter from the options object Right delimiter for template tags. Defaults to ‘}}’.

Return type:

string

Returns:

a string, the current value for TemplateRightDelimiter.

GetTemplateStrictMode()

Gets the value TemplateStrictMode from the options object If “Strict Mode” is enabled, when a template key is missing from the json data an exception will be thrown. If “Strict Mode” is disabled (default), the tag will be replaced with no content.

Return type:

boolean

Returns:

a bool, the current value for TemplateStrictMode.

GetUpdateTableOfContents()

Gets the value UpdateTableOfContents from the options object Updates the table of contents in the document so it matches the actual locations of headings/bookmarks. By default, the table of contents is not updated. Enabling this option may negatively affect conversion speed.

Return type:

boolean

Returns:

a bool, the current value for UpdateTableOfContents.

SetApplyPageBreaksToSheet(value)

Sets the value for ApplyPageBreaksToSheet in the options object Whether we should split Excel workheets into pages so that the output resembles print output. If set to false (the default), Excel sheets will be placed one per page, except in the case where the sheets are very large

Parameters:

value: – the new value for ApplyPageBreaksToSheet

Return type:

OfficeToPDFOptions

Returns:

this object, for call chaining

SetDisplayChangeTracking(value)

Sets the value for DisplayChangeTracking in the options object If this option is true, will display office change tracking markup present in the document (i.e, red strikethrough of deleted content and underlining of new content). Otherwise displays the resolved document content, with no markup. Defaults to true.

Parameters:

value: – the new value for DisplayChangeTracking

Return type:

OfficeToPDFOptions

Returns:

this object, for call chaining

SetDisplayHiddenText(value)

Sets the value for DisplayHiddenText in the options object Display any hidden text that is present in the document (i.e., text that has been marked as ‘Hidden’ in the font style). By default, hidden text will not be displayed.

Parameters:

value: – the new value for DisplayHiddenText

Return type:

OfficeToPDFOptions

Returns:

this object, for call chaining

SetExcelDefaultCellBorderWidth(value)

Sets the value for ExcelDefaultCellBorderWidth in the options object Cell border width for table cells that would normally be drawn with no border. In units of points. Can be used to achieve a similar effect to the “show gridlines” display option within Microsoft Excel.

Parameters:

value: – the new value for ExcelDefaultCellBorderWidth

Return type:

OfficeToPDFOptions

Returns:

this object, for call chaining

SetExcelMaxAllowedCellCount(value)

Sets the value for ExcelMaxAllowedCellCount in the options object Conversion will throw an exception if the number of cells in a Microsoft Excel document is above the set MaxAllowedCellCount. Used for early termination of resource intensive conversions. Setting this value to 250000 will allow the vast majority of Excel documents to convert without issue, while keeping RAM usage to a reasonable level. By default there is no limit to the number of allowed cells.

Parameters:

value: – the new value for ExcelMaxAllowedCellCount

Return type:

OfficeToPDFOptions

Returns:

this object, for call chaining

SetHideTotalNumberOfPages(value)

Sets the value for HideTotalNumberOfPages in the options object If the document has an element that displays the total number of pages and the total number of pages is unknown beforehand, remove those elements from the document.

Parameters:

value: – the new value for HideTotalNumberOfPages

Return type:

OfficeToPDFOptions

Returns:

this object, for call chaining

SetLayoutResourcesPluginPath(value)

Sets the value for LayoutResourcesPluginPath in the options object The path at which the pdftron-provided font resource plugin resides

Parameters:

value: – the new value for LayoutResourcesPluginPath

Return type:

OfficeToPDFOptions

Returns:

this object, for call chaining

SetLocale(value)

Sets the value for Locale in the options object ISO 639-1 code of the locale to be applied during conversion. For example: ‘en-US’, ‘ar-SA’, ‘de-DE’, etc. Currently only applied during xls/xlsx conversions.

Parameters:

value: – the new value for Locale

Return type:

OfficeToPDFOptions

Returns:

this object, for call chaining

SetPassword(value)

Sets the value for Password in the options object Password used to decrypt password-protected office documents.

Parameters:

value: – the new value for Password

Return type:

OfficeToPDFOptions

Returns:

this object, for call chaining

SetResourceDocPath(value)

Sets the value for ResourceDocPath in the options object The path at which a .docx resource document resides

Parameters:

value: – the new value for ResourceDocPath

Return type:

OfficeToPDFOptions

Returns:

this object, for call chaining

SetSmartSubstitutionPluginPath(value)

Sets the value for SmartSubstitutionPluginPath in the options object The path at which the pdftron-provided font resource plugin resides

Parameters:

value: – the new value for SmartSubstitutionPluginPath

Return type:

OfficeToPDFOptions

Returns:

this object, for call chaining

SetStructureTagLevel(value)

Sets the value for StructureTagLevel in the options object Specifies the level of document structure tags to include in the PDF for accessibility purposes.

Parameters:

value: – the new value for StructureTagLevel

Return type:

OfficeToPDFOptions

Returns:

this object, for call chaining

SetTemplateLeftDelimiter(value)

Sets the value for TemplateLeftDelimiter in the options object Left delimiter for template tags. Defaults to ‘{{‘.

Parameters:

value: – the new value for TemplateLeftDelimiter

Return type:

OfficeToPDFOptions

Returns:

this object, for call chaining

SetTemplateParamsJson(value)

Sets the value for TemplateParamsJson in the options object JSON string representing the data to be merged into a PDFTron office template. For a more featureful template API, see CreateOfficeTemplate.

Parameters:

value: – the new value for TemplateParamsJson

Return type:

OfficeToPDFOptions

Returns:

this object, for call chaining

SetTemplateRightDelimiter(value)

Sets the value for TemplateRightDelimiter in the options object Right delimiter for template tags. Defaults to ‘}}’.

Parameters:

value: – the new value for TemplateRightDelimiter

Return type:

OfficeToPDFOptions

Returns:

this object, for call chaining

SetTemplateStrictMode(value)

Sets the value for TemplateStrictMode in the options object If “Strict Mode” is enabled, when a template key is missing from the json data an exception will be thrown. If “Strict Mode” is disabled (default), the tag will be replaced with no content.

Parameters:

value: – the new value for TemplateStrictMode

Return type:

OfficeToPDFOptions

Returns:

this object, for call chaining

SetUpdateTableOfContents(value)

Sets the value for UpdateTableOfContents in the options object Updates the table of contents in the document so it matches the actual locations of headings/bookmarks. By default, the table of contents is not updated. Enabling this option may negatively affect conversion speed.

Parameters:

value: – the new value for UpdateTableOfContents

Return type:

OfficeToPDFOptions

Returns:

this object, for call chaining

e_default = 0

Default level of structure tags, good for accessibility.

e_none = 1

No structure tags. This can be used to get smaller file sizes.

property thisown

The membership flag

class apryse_sdk.Optimizer(args, kwargs)

Bases: object

The Optimizer class provides functionality for optimizing/shrinking output PDF files.

‘pdftron.PDF.Optimizer’ is an optional PDFNet Add-On utility class that can be used to optimize PDF documents by reducing the file size, removing redundant information, and compressing data streams using the latest in image compression technology. PDF Optimizer can compress and shrink PDF file size with the following operations: - Remove duplicated fonts, images, ICC profiles, and any other data stream. - Optionally convert high-quality or print-ready PDF files to small, efficient and web-ready PDF. - Optionally down-sample large images to a given resolution. - Optionally compress or recompress PDF images using JBIG2 and JPEG2000 compression formats. - Compress uncompressed streams and remove unused PDF objects.

Notes: ‘Optimizer’ is available as a separately licensable add-on to PDFNet core license.

See ‘pdftron.PDF.Flattener’ for alternate approach to optimize PDFs for fast viewing on mobile devices and the Web.

static Optimize(args)

property thisown

The membership flag

class apryse_sdk.OptimizerSettings

Bases: object

A class that stores settings for the optimizer

RemoveCustomEntries(should_remove)

Enable or disable removal of custom entries in the PDF. By default custom entries are removed.<summary>

Parameters:

should_remove (boolean) – if true custom entries will be removed.

SetColorImageSettings(settings)

updates the settings for color image processing

SetGrayscaleImageSettings(settings)

updates the settings for grayscale image processing

SetMonoImageSettings(settings)

updates the settings for monochrome image processing

SetTextSettings(settings)

updates the settings for text processing

property m_color_image_settings

property m_grayscale_image_settings

property m_mono_image_settings

property m_remove_custom

property m_text_settings

property thisown

The membership flag

apryse_sdk.Optimizer_Optimize(args)

class apryse_sdk.OutputOptionsOCR

Bases: object

A class containing OCR options common to the ToHtml, ToWord, ToExcel, ToPowerPoint functions

static LanguageChoiceToString(language)

static PreferredOCRChoiceToString(engine)

e_engine_default = 0

e_engine_tesseract = 1

e_lang_auto = 0

e_lang_catalan = 1

e_lang_danish = 2

e_lang_dutch = 9

e_lang_english = 4

e_lang_finnish = 6

e_lang_french = 7

e_lang_german = 3

e_lang_italian = 8

e_lang_norwegian = 10

e_lang_polish = 12

e_lang_portuguese = 11

e_lang_romanian = 13

e_lang_russian = 14

e_lang_slovenian = 15

e_lang_spanish = 5

e_lang_swedish = 16

e_lang_turkish = 17

property thisown

The membership flag

apryse_sdk.OutputOptionsOCR_LanguageChoiceToString(language)

apryse_sdk.OutputOptionsOCR_PreferredOCRChoiceToString(engine)

class apryse_sdk.PDF2HtmlReflowParagraphsModule

Bases: object

The class PDF2HtmlReflowParagraphsModule. static interface to PDFTron SDKs PDF to HTML functionality

static IsModuleAvailable()

Find out whether the pdf2html module is available (and licensed).

Return type:

boolean

Returns:

returns true if pdf2html operations can be performed.

property thisown

The membership flag

apryse_sdk.PDF2HtmlReflowParagraphsModule_IsModuleAvailable()

Find out whether the pdf2html module is available (and licensed).

Return type:

boolean

Returns:

returns true if pdf2html operations can be performed.

class apryse_sdk.PDF2WordModule

Bases: object

The class PDF2WordModule. static interface to PDFTron SDKs PDF to Word functionality

static IsModuleAvailable()

Find out whether the pdf2word module is available (and licensed).

Return type:

boolean

Returns:

returns true if pdf2word operations can be performed.

property thisown

The membership flag

apryse_sdk.PDF2WordModule_IsModuleAvailable()

Find out whether the pdf2word module is available (and licensed).

Return type:

boolean

Returns:

returns true if pdf2word operations can be performed.

class apryse_sdk.PDFACompliance(args)

Bases: object

PDFACompliance class is used to validate PDF documents for PDF/A (ISO 19005:1/2/3) compliance or to convert existing PDF files to PDF/A compliant documents.

The conversion option analyzes the content of existing PDF files and performs a sequence of modifications in order to produce a PDF/A compliant document. Features that are not suitable for long-term archiving (such as encryption, obsolete compression schemes, missing fonts, or device-dependent color) are replaced with their PDF/A compliant equivalents. Because the conversion process applies only necessary changes to the source file, the information loss is minimal. Also, because the converter provides a detailed report for each change, it is simple to inspect changes and to determine whether the conversion loss is acceptable.

The validation option in PDF/A Manager can be used to quickly determine whether a PDF file fully complies with the PDF/A specification according to the international standard ISO 19005:1/2/3. For files that are not compliant, the validation option can be used to produce a detailed report of compliance violations as well as a list of relevant error objects.

Key Functions: - Checks if a PDF file is compliant with PDF/A (ISO 19005:1/2/3) specification. - Converts any PDF to a PDF/A compliant document. - Supports PDF/A-1a, PDF/A-1b, PDF/A-2b - Produces a detailed report of compliance violations and associated PDF objects. - Keeps the required changes a minimum, preserving the consistency of the original. - Tracks all changes to allow for automatic assessment of data loss. - Allows user to customize compliance checks or omit specific changes. - Preserves tags, logical structure, and color information in existing PDF documents. - Offers automatic font substitution, embedding, and subsetting options. - Supports automation and batch operation. PDF/A Converter is designed to be used

in unattended mode in high throughput server or batch environments

Destroy()

Frees the native memory of the object.

static GetDeclaredConformance(in_doc)

Retrieves whether document’s XMP metadata claims PDF/A conformance and to what part and level.

Parameters:

in_doc (PDFDoc) – the document

Return type:

int

Returns:

Presumptive PDFA part number and conformance level, as an enumerated value.

GetError(idx)

Return type:

int

Returns:

The error identifier.

Parameters:

idx (int) – The index in the array of error code identifiers. The array is indexed starting from zero.

Raises:

throws an Exception if the index is outside the array bounds.

GetErrorCount()

Return type:

int

Returns:

The number of compliance violations.

static GetPDFAErrorMessage(id)

Parameters:

id (int) – error code identifier (obtained using GetError() method).

Return type:

string

Returns:

A descriptive error message for the given error identifier.

GetRefObj(id, err_idx)

Return type:

int

Returns:

A specific object reference associated with a given error type. The return value is a PDF object identifier (i.e. object number for ‘pdftron.SDF.Obj)) for the that is associated with the error.

Parameters:

• id (int) – error code identifier (obtained using GetError() method).

• err_idx (int) – The index in the array of object references. The array is indexed starting from zero.

Raises:

throws an Exception if the index is outside the array bounds.

GetRefObjCount(id)

Return type:

int

Returns:

The number of object references associated with a given error.

Parameters:

id (int) – error code identifier (obtained using GetError() method).

SaveAs(args)

Overload 1:

Serializes the converted PDF/A document to a file on disk. Notes: This method assumes that the first parameter passed in PDFACompliance

ructor (i.e. the convert parameter) is set to ‘true’.

type file_path:

string

param file_path:

• the output file name.

type linearized:

boolean

param linearized:

• An optional flag used to specify whether the resulting

PDF/A document should be web-optimized (linearized).

Overload 2:

Serializes the converted PDF/A document to a memory buffer. Notes: This method assumes that the first parameter passed in PDFACompliance

ructor (i.e. the convert parameter) is set to ‘true’.

type linearized:

boolean

param linearized:

• An optional flag used to specify whether the resulting

PDF/A document should be web-optimized (linearized).

rtype:

std::vector< unsigned char,std::allocator< unsigned char > >

return:

The converted document saved as a memory buffer.

Overload 3:

Serializes the converted PDF/A document to a memory buffer. Notes: This method assumes that the first parameter passed in PDFACompliance

ructor (i.e. the convert parameter) is set to ‘true’.

param linearized:

• An optional flag used to specify whether the resulting

PDF/A document should be web-optimized (linearized).

rtype:

std::vector< unsigned char,std::allocator< unsigned char > >

return:

The converted document saved as a memory buffer.

e_Level1A = 1

e_Level1B = 2

e_Level2A = 3

e_Level2B = 4

e_Level2U = 5

e_Level3A = 6

e_Level3B = 7

e_Level3U = 8

e_Level4 = 9

e_Level4E = 10

e_Level4F = 11

e_NoConformance = 0

e_PDFA0_1_0 = 10

Invalid PDF structure.

e_PDFA0_1_1 = 11

Corrupt document.

e_PDFA0_1_2 = 12

Corrupt content stream.

e_PDFA0_1_3 = 13

Using JPEG2000 compression (PDF 1.4 compatibility).

e_PDFA0_1_4 = 14

Contains compressed object streams (PDF 1.4 compatibility).

e_PDFA0_1_5 = 15

Contains cross-reference streams (PDF 1.4 compatibility).

e_PDFA11_0_0 = 11000

Catalog contains Requirements key.

e_PDFA1_10_1 = 1101

Using LZW compression.

e_PDFA1_10_2 = 1102

Invalid use of Crypt filter.

e_PDFA1_10_3 = 1103

Bad stream Filter.

e_PDFA1_11_1 = 1111

A file specification dictionary contains a non-compliant embedded file (EF key).

e_PDFA1_11_2 = 1112

Contains the EmbeddedFiles key

e_PDFA1_12_1 = 1121

Array contains more than 8191 elements

e_PDFA1_12_10 = 11210

Bad Permission Dictionary

e_PDFA1_12_2 = 1122

Dictionary contains more than 4095 elements

e_PDFA1_12_3 = 1123

Name with more than 127 bytes

e_PDFA1_12_4 = 1124

Contains an integer value outside of the allowed range [-2^31, 2^31-1],

e_PDFA1_12_5 = 1125

Exceeds the maximum number (8,388,607) of indirect objects in a PDF file.

e_PDFA1_12_6 = 1126

The number of nested q/Q operators is greater than 28.

e_PDFA1_13_1 = 1131

Optional content (layers) not allowed.

e_PDFA1_13_5 = 1135

Page dimensions are outside of the allowed range (3-14400).

e_PDFA1_2_1 = 121

Document does not start with % character.

e_PDFA1_2_2 = 122

File header line not followed by % and 4 characters > 127.

e_PDFA1_2_3 = 123

Bad file header.

e_PDFA1_3_1 = 131

The trailer dictionary does not contain ID.

e_PDFA1_3_2 = 132

Trailer dictionary contains Encrypt.

e_PDFA1_3_3 = 133

Data after last EOF marker.

e_PDFA1_3_4 = 134

ID in 1st page and last trailer are different.

Type:

Linearized file

e_PDFA1_4_1 = 141

starting object number and range not separated by a single space.

Type:

Subsection header

e_PDFA1_4_2 = 142

‘xref’ and cross reference subsection header not separated by a single EOL marker.

e_PDFA1_6_1 = 161

Invalid hexadecimal strings used.

e_PDFA1_7_1 = 171

The ‘stream’ token is not followed by CR and LF or a single LF.

e_PDFA1_7_2 = 172

The ‘endstream’ token is not preceded by EOL.

e_PDFA1_7_3 = 173

The value of Length does not match the number of bytes.

e_PDFA1_7_4 = 174

A stream object dictionary contains the F, FFilter, or FDecodeParms keys.

e_PDFA1_8_1 = 181

Object number and generation number are not separated by a single white-space.

e_PDFA1_8_2 = 182

Generation number and ‘obj’ are not separated by a single white-space.

e_PDFA1_8_3 = 183

Object number not preceded by EOL marker

e_PDFA1_8_4 = 184

‘endobj’ not preceded by EOL marker

e_PDFA1_8_5 = 185

‘obj’ not followed by EOL marker

e_PDFA1_8_6 = 186

‘endobj’ not followed by EOL marker

e_PDFA1_8_7 = 187

Invalid UTF8 string

e_PDFA2_10_1 = 2101

Illegal operator.

e_PDFA2_10_20 = 21020

Page Group entry is missing in a document without OutputIntent.

e_PDFA2_10_21 = 21021

Invalid blend mode.

e_PDFA2_2_1 = 221

DestOutputProfile-s in OutputIntents array do not match.

e_PDFA2_3_10 = 2310

Contains DestOutputProfileRef

e_PDFA2_3_2 = 232

Not a valid ICC color profile.

e_PDFA2_3_3 = 233

The N entry does not match the number of color components in the embedded ICC profile.

e_PDFA2_3_3_1 = 2331

Device-specific color space used, but no GTS_PDFA1 OutputIntent.

e_PDFA2_3_3_2 = 2332

Device-specific color space, does not match OutputIntent.

e_PDFA2_3_4_1 = 2341

Device-specific color space used in an alternate color space.

e_PDFA2_4_1 = 241

Image with Alternates key.

e_PDFA2_4_2 = 242

Image with OPI key.

e_PDFA2_4_2_10 = 24220

OPM is 1

e_PDFA2_4_2_11 = 24221

Incorrect colorant specification in DeviceN

e_PDFA2_4_2_12 = 24222

tintTransform is different in Separations with the same colorant name.

e_PDFA2_4_2_13 = 24223

alternateSpace is different in Separations with the same colorant name.

e_PDFA2_4_3 = 243

Image with invalid rendering intent.

e_PDFA2_4_4 = 244

Image with Interpolate key set to true.

e_PDFA2_5_1 = 251

XObject with OPI key.

e_PDFA2_5_10 = 2510

HTP entry in ExtGState.

e_PDFA2_5_11 = 2511

Unsupported HalftoneType.

e_PDFA2_5_12 = 2512

Uses HalftoneName key.

e_PDFA2_5_2 = 252

PostScript XObject.

e_PDFA2_6_1 = 261

Contains a reference XObject.

e_PDFA2_7_1 = 271

Contains an XObject that is not supported (e.g. PostScript XObject).

e_PDFA2_8_1 = 281

Contains an invalid Transfer Curve in the extended graphics state.

e_PDFA2_8_3_1 = 2831

Only the JPX baseline is supported.

Type:

JPEG2000

e_PDFA2_8_3_2 = 2832

Invalid number of colour channels.

Type:

JPEG2000

e_PDFA2_8_3_3 = 2833

Invalid color space.

Type:

JPEG2000

e_PDFA2_8_3_4 = 2834

The bit-depth JPEG2000 data must be in range 1-38.

Type:

JPEG2000

e_PDFA2_8_3_5 = 2835

All colour channels in the JPEG2000 data must have the same bit-depth.

Type:

JPEG2000

e_PDFA2_9_1 = 291

Use of an invalid rendering intent.

e_PDFA3_2_1 = 321

Embedded font is damaged.

e_PDFA3_3_1 = 331

Incompatible CIDSystemInfo entries

e_PDFA3_3_2 = 332

Type 2 CIDFont without CIDToGIDMap

e_PDFA3_3_3_1 = 3331

CMap not embedded

e_PDFA3_3_3_2 = 3332

Inconsistent WMode in embedded CMap dictionary and stream.

e_PDFA3_4_1 = 341

The font is not embedded.

e_PDFA3_5_1 = 351

Embedded composite (Type0) font program does not define all font glyphs.

e_PDFA3_5_2 = 352

Embedded Type1 font program does not define all font glyphs.

e_PDFA3_5_3 = 353

Embedded TrueType font program does not define all font glyphs.

e_PDFA3_5_4 = 354

The font descriptor dictionary does not include a CIDSet stream for CIDFont subset.

e_PDFA3_5_5 = 355

The font descriptor dictionary does not include a CharSet string for Type1 font subset.

e_PDFA3_5_6 = 356

CIDSet in subset font is incomplete.

e_PDFA3_6_1 = 361

Widths in embedded font are inconsistent with /Widths entry in the font dictionary.

e_PDFA3_7_1 = 371

A non-symbolic TrueType font must use WinAnsiEncoding or MacRomanEncoding.

e_PDFA3_7_2 = 372

A symbolic TrueType font must not specify encoding.

e_PDFA3_7_3 = 373

A symbolic TrueType font does not have exactly one entry in cmap table.

e_PDFA3_8_1 = 381

The font dictionary is missing ‘ToUnicode’ entry.

e_PDFA4_1 = 41

Transparency used (ExtGState with soft mask).

e_PDFA4_2 = 42

Transparency used (XObject with soft mask).

e_PDFA4_3 = 43

Transparency used (Page or Form XObject with transparency group).

e_PDFA4_4 = 44

Transparency used (Blend mode is not ‘Normal’).

e_PDFA4_5 = 45

Transparency used (‘CA’ value is not 1.0).

e_PDFA4_6 = 46

Transparency used (‘ca’ value is not 1.0).

e_PDFA5_2_1 = 521

Unknown annotation type.

e_PDFA5_2_10 = 5210

PolyLine annotation is not permitted.

e_PDFA5_2_11 = 5211

Screen annotation is not permitted.

e_PDFA5_2_2 = 522

FileAttachment annotation is not permitted.

e_PDFA5_2_3 = 523

Sound annotation is not permitted.

e_PDFA5_2_4 = 524

Movie annotation is not permitted.

e_PDFA5_2_5 = 525

Redact annotation is not permitted.

e_PDFA5_2_6 = 526

3D annotation is not permitted.

e_PDFA5_2_7 = 527

Caret annotation is not permitted.

e_PDFA5_2_8 = 528

Watermark annotation is not permitted.

e_PDFA5_2_9 = 529

Polygon annotation is not permitted.

e_PDFA5_3_1 = 531

An annotation dictionary contains the CA key with a value other than 1.0.

e_PDFA5_3_2_1 = 5321

An annotation dictionary is missing F key.

e_PDFA5_3_2_2 = 5322

An annotation’s ‘Print’ flag is not set.

e_PDFA5_3_2_3 = 5323

An annotation’s ‘Hidden’ flag is set.

e_PDFA5_3_2_4 = 5324

An annotation’s ‘Invisible’ flag is set.

e_PDFA5_3_2_5 = 5325

An annotation’s ‘NoView’ flag is set.

e_PDFA5_3_3_1 = 5331

An annotation’s C entry present but no OutputIntent present

e_PDFA5_3_3_2 = 5332

An annotation’s C entry present but OutputIntent has non-RGB destination profile

e_PDFA5_3_3_3 = 5333

An annotation’s IC entry present but no OutputIntent present

e_PDFA5_3_3_4 = 5334

An annotation’s IC entry present and OutputIntent has non-RGB destination profile

e_PDFA5_3_4_0 = 5340

Annotation is missing AP entry.

e_PDFA5_3_4_1 = 5341

An annotation AP dictionary has entries other than the N entry.

e_PDFA5_3_4_2 = 5342

An annotation AP dictionary does not contain N entry

e_PDFA5_3_4_3 = 5343

AP has an N entry whose value is invalid.

e_PDFA6_10_0 = 6100

PresSteps is not allowed

e_PDFA6_10_1 = 6101

AlternatePresentations not allowed

e_PDFA6_1_1 = 611

Contains an action type that is not permitted.

e_PDFA6_1_2 = 612

Contains a non-predefined Named action.

e_PDFA6_2_1 = 621

The document catalog dictionary contains AA entry.

e_PDFA6_2_11_5 = 62115

Some characters map to 0 or FFFE.

e_PDFA6_2_11_6 = 62116

Some text can’t be mapped to Unicode

e_PDFA6_2_11_7 = 62117

PUA characters are missing ActualText

e_PDFA6_2_11_8 = 62118

Use of .notdef glyph

e_PDFA6_2_2 = 622

Contains the JavaScript key.

e_PDFA6_2_3 = 623

Invalid destination.

e_PDFA6_9_1 = 69001

Optional content Missing Name entry

e_PDFA6_9_3 = 69003

Optional content Contains AS entry

e_PDFA7_11_1 = 7111

Missing PDF/A identifier

e_PDFA7_11_2 = 7112

Invalid PDF/A identifier namespace

e_PDFA7_11_3 = 7113

Invalid PDF/A conformance level.

e_PDFA7_11_4 = 7114

Invalid PDF/A part number.

e_PDFA7_11_5 = 7115

Invalid PDF/A amendment identifier.

e_PDFA7_2_1 = 721

The document catalog does not contain Metadata stream.

e_PDFA7_2_2 = 722

The Metadata object stream contains Filter key.

e_PDFA7_2_3 = 723

The XMP Metadata stream is not valid.

e_PDFA7_2_4 = 724

XMP property not predefined and no extension schema present.

e_PDFA7_2_5 = 725

XMP not included in ‘xpacket’.

e_PDFA7_3_1 = 731

Document information entry ‘Title’ not synchronized with XMP.

e_PDFA7_3_2 = 732

Document information entry ‘Author’ not synchronized with XMP.

e_PDFA7_3_3 = 733

Document information entry ‘Subject’ not synchronized with XMP.

e_PDFA7_3_4 = 734

Document information entry ‘Keywords’ not synchronized with XMP.

e_PDFA7_3_5 = 735

Document information entry ‘Creator’ not synchronized with XMP.

e_PDFA7_3_6 = 736

Document information entry ‘Producer’ not synchronized with XMP.

e_PDFA7_3_7 = 737

Document information entry ‘CreationDate’ not synchronized with XMP.

e_PDFA7_3_8 = 738

Document information entry ‘ModDate’ not synchronized with XMP.

e_PDFA7_3_9 = 739

Wrong value type for predefined XMP property.

e_PDFA7_5_1 = 751

‘bytes’ and ‘encoding’ attributes are allowed in the header of an XMP packet.

e_PDFA7_8_1 = 781

XMP Extension schema doesn’t have a description.

e_PDFA7_8_10 = 7810

valueType’ not found.

Type:

‘pdfaProperty

e_PDFA7_8_11 = 7811

The required namespace prefix for extension schema is ‘pdfaExtension’.

e_PDFA7_8_12 = 7812

The required field namespace prefix is ‘pdfaSchema’.

e_PDFA7_8_13 = 7813

The required field namespace prefix is ‘pdfaProperty’.

e_PDFA7_8_14 = 7814

The required field namespace prefix is ‘pdfaType’.

e_PDFA7_8_15 = 7815

The required field namespace prefix is ‘pdfaField’.

e_PDFA7_8_16 = 7816

valueType’ not found.

Type:

‘pdfaSchema

e_PDFA7_8_17 = 7817

valueType’ is using a wrong value type.

Type:

‘pdfaSchema

e_PDFA7_8_18 = 7818

Required property ‘valueType’ missing in PDF/A Schema Value Type.

e_PDFA7_8_19 = 7819

‘pdfaType :type’ not found.

e_PDFA7_8_2 = 782

XMP Extension schema is not valid. Required property ‘namespaceURI’ might be missing in PDF/A Schema value Type.

e_PDFA7_8_20 = 7820

‘pdfaType :type’ is using a wrong value type.

e_PDFA7_8_21 = 7821

description’ not found.

Type:

‘pdfaType

e_PDFA7_8_22 = 7822

namespaceURI’ not found.

Type:

‘pdfaType

e_PDFA7_8_23 = 7823

field’ is using a wrong value type.

Type:

‘pdfaType

e_PDFA7_8_24 = 7824

name’ not found.

Type:

‘pdfaField

e_PDFA7_8_25 = 7825

name’ is using a wrong value type.

Type:

‘pdfaField

e_PDFA7_8_26 = 7826

valueType’ not found.

Type:

‘pdfaField

e_PDFA7_8_27 = 7827

valueType’ is using a wrong type.

Type:

‘pdfaField

e_PDFA7_8_28 = 7828

description’ not found.

Type:

‘pdfaField

e_PDFA7_8_29 = 7829

description’ is using a wrong type.

Type:

‘pdfaField

e_PDFA7_8_3 = 783

schemas’ not found.

Type:

‘pdfaExtension

e_PDFA7_8_30 = 7830

Required description for ‘pdfaField::valueType’ is missing.

e_PDFA7_8_31 = 7831

A property doesn’t match its custom schema type.

e_PDFA7_8_4 = 784

schemas’ is using a wrong value type.

Type:

‘pdfaExtension

e_PDFA7_8_5 = 785

property’ not found.

Type:

‘pdfaExtension

e_PDFA7_8_6 = 786

property’ is using a wrong value type.

Type:

‘pdfaExtension

e_PDFA7_8_7 = 787

name’ not found.

Type:

‘pdfaProperty

e_PDFA7_8_8 = 788

name’ is using a wrong value type.

Type:

‘pdfaProperty

e_PDFA7_8_9 = 789

property’ sequence.

Type:

A description for a property is missing in ‘pdfaSchema

e_PDFA8_1 = 81

FileSpec is missing F or UF key

e_PDFA8_2_2 = 822

The PDF is not marked as Tagged PDF.

e_PDFA8_3_3_1 = 8331

Bad StructTreeRoot

e_PDFA8_3_3_2 = 8332

Each structure element dictionary in the structure hierarchy must have a Type entry with the name value of StructElem.

e_PDFA8_3_4_1 = 8341

A non-standard structure type does not map to a standard type.

e_PDFA9_1 = 91

An interactive form field contains an action.

e_PDFA9_2 = 92

The NeedAppearances flag in the interactive form dictionary is set to true.

e_PDFA9_3 = 93

AcroForms contains XFA.

e_PDFA9_4 = 94

Catalog contains NeedsRendering.

e_PDFA_3E1 = 1

Embedded file has no MIME type entry

e_PDFA_3E1_1 = 101

Embedded file Params has no ModDate entry

e_PDFA_3E2 = 2

Embedded file has no AFRelationship

e_PDFA_3E3 = 3

Doc catalog is missing AF entry

e_PDFA_4_6_1_12_1 = 461121

If the Version key is present in the document catalog dictionary, the first character in its value shall be a 2 (32h) and the second character of its value shall be a PERIOD (2Eh) (decimal point). The third character shall be a decimal digit. The number of characters of the value of the Version key shall be exactly 3.

e_PDFA_4_6_1_3_4 = 46134

The Info key shall not be present in the trailer dictionary unless there exists a PieceInfo entry in the document catalog dictionary.

e_PDFA_4_6_1_3_5 = 46135

If a document information dictionary is present, it shall only contain a ModDate entry.

e_PDFA_4_6_1_6_1_3 = 461613

3D stream shall have a Subtype entry with a value which is either U3D or PRC.

e_PDFA_4_6_2_10_6_1 = 4621061

For all non-symbolic TrueType fonts used for rendering, the embedded TrueType font program shall contain at least Microsoft Unicode (3,1 - Platform ID=3, Encoding ID=1), or Macintosh Roman (1,0 - Platform ID=1, Encoding ID=0) ‘cmap’ subtable that all necessary glyph lookups are able to be carried out

e_PDFA_4_6_2_10_6_4 = 4621064

Symbolic TrueType fonts shall not contain an Encoding entry in the font dictionary, and the ‘cmap’ subtable in the embedded font program shall either contain the Microsoft Symbol (3,0 - Platform ID=3, Encoding ID=0) or the Mac Roman (1,0 - Platform ID=1, Encoding ID=0) encoding.

e_PDFA_4_6_2_2_3 = 46223

A content stream’s named resource not defined by a resource dictionary

e_PDFA_4_6_2_4_2_3 = 462423

An ICCBased CMYK color space is identical to the current PDF/A OutputIntent color profile or the current transparency blending color space.

e_PDFA_4_6_2_5_3 = 46253

HTO entry in ExtGState.

e_PDFA_4_6_6_3_1 = 46631

E, X, D, U, Fo and Bl.

Type:

A document catalog or a page dictionary contains an AA entry and its value contains key(s) not from the following list

e_PDFA_4_6_7_3_5 = 46735

Invalid PDF/A revision.

e_PDFA_4_6_9_5 = 4695

Doc catalog is missing EmbeddedFiles key

e_PDFA_LAST = 4621065

property mp_pdfac

property thisown

The membership flag

apryse_sdk.PDFACompliance_GetDeclaredConformance(in_doc)

Retrieves whether document’s XMP metadata claims PDF/A conformance and to what part and level.

Parameters:

in_doc (PDFDoc) – the document

Return type:

int

Returns:

Presumptive PDFA part number and conformance level, as an enumerated value.

apryse_sdk.PDFACompliance_GetPDFAErrorMessage(id)

Parameters:

id (int) – error code identifier (obtained using GetError() method).

Return type:

string

Returns:

A descriptive error message for the given error identifier.

class apryse_sdk.PDFAOptions(level)

Bases: object

GetConformance()

Gets the value Conformance from the options object The PDF/A conformance level.

Return type:

int

Returns:

a PDFACompliance::Conformance, the current value for Conformance.

GetDPI()

Gets the value DPI from the options object DPI used for flattening.

Return type:

int

Returns:

a UInt32, the current value for DPI.

GetFirstStop()

Gets the value FirstStop from the options object Whether to stop processing after the first PDF/A error is detected.

Return type:

boolean

Returns:

a bool, the current value for FirstStop.

GetFlattenTransparency()

Gets the value FlattenTransparency from the options object Whether to flatten transparency in PDF/A-1 mode.

Return type:

boolean

Returns:

a bool, the current value for FlattenTransparency.

GetMaxRefObjs()

Gets the value MaxRefObjs from the options object The maximum number of object references per error condition.

Return type:

int

Returns:

a UInt32, the current value for MaxRefObjs.

GetPassword()

Gets the value Password from the options object The password to be used for encrypted PDF documents.

Return type:

string

Returns:

a string, the current value for Password.

SetConformance(value)

Sets the value for Conformance in the options object The PDF/A conformance level.

Parameters:

value: – the new value for Conformance

Return type:

PDFAOptions

Returns:

this object, for call chaining

SetDPI(value)

Sets the value for DPI in the options object DPI used for flattening.

Parameters:

value: – the new value for DPI

Return type:

PDFAOptions

Returns:

this object, for call chaining

SetFirstStop(value)

Sets the value for FirstStop in the options object Whether to stop processing after the first PDF/A error is detected.

Parameters:

value: – the new value for FirstStop

Return type:

PDFAOptions

Returns:

this object, for call chaining

SetFlattenTransparency(value)

Sets the value for FlattenTransparency in the options object Whether to flatten transparency in PDF/A-1 mode.

Parameters:

value: – the new value for FlattenTransparency

Return type:

PDFAOptions

Returns:

this object, for call chaining

SetMaxRefObjs(value)

Sets the value for MaxRefObjs in the options object The maximum number of object references per error condition.

Parameters:

value: – the new value for MaxRefObjs

Return type:

PDFAOptions

Returns:

this object, for call chaining

SetPassword(value)

Sets the value for Password in the options object The password to be used for encrypted PDF documents.

Parameters:

value: – the new value for Password

Return type:

PDFAOptions

Returns:

this object, for call chaining

property thisown

The membership flag

class apryse_sdk.PDFDoc(args)

Bases: object

PDFDoc is a high-level class describing a single PDF (Portable Document Format) document. Most applications using PDFNet will use this class to open existing PDF documents, or to create new PDF documents from scratch.

The class offers a number of entry points into the document. For example,

• To access pages use pdfdoc.GetPageIterator() or pdfdoc.GetPage(page_num).

• To access form fields use pdfdoc.GetFieldIterator(), pdfdoc.GetFieldIterator(name) or pdfdoc.GetField(name).

• To access document’s meta-data use pdfdoc.GetDocInfo().

• To access the outline tree use pdfdoc.GetFirstBookmark().

• To access low-level Document Catalog use pdfdoc.GetRoot().

…

The class also offers utility methods to slit and merge PDF pages, to create new pages, to flatten forms, to change security settings, etc.

AddFileAttachment(file_key, embedded_file)

Associates a file attachment with the document.

The file attachment will be displayed in the user interface of a viewer application (in Acrobat this is File Attachment tab). The function differs from Annot.CreateFileAttachment() because it associates the attachment with the whole document instead of an annotation on a specific page.

Parameters:

• file_key (string) – A key/name under which the attachment will be stored.

• embedded_file (FileSpec) – Embedded file stream

Notes: Another way to associate a file attachment with the document is using SDF::NameTree:

SDF::NameTree names = SDF::NameTree::Create(doc, "EmbeddedFiles");
names.Put(file_key, file_keysz, embedded_file.GetSDFObj());

AddHighlights(hilite)

AddHighlights is used to highlight text in a document using ‘Adobe’s Highlight File Format’ (Technical Note #5172 ). The method will parse the character offset data and modify the current document by adding new highlight annotations.

Parameters:

hilite (string) – a string representing the filename for the highlight file or or a data buffer containing XML data.

Raises:

An exception will be thrown if the XML file is malformed or os out of sync with the document.

AddRootBookmark(root_bookmark)

Adds/links the specified Bookmark to the root level of document’s outline tree.

Parameters:

root_bookmark (Bookmark) – Bookmark to Add/link

Notes: parameter ‘root_bookmark’ must not be linked (must not be belong) to a bookmark tree.

AddSignatureHandler(signature_handler)

Adds a signature handler to the signature manager.

Parameters:

signature_handler (SignatureHandler) – The signature handler instance to add to the signature manager.

Return type:

int

Returns:

A unique ID representing the SignatureHandler within the SignatureManager.

AddStdSignatureHandler(args)

Overload 1:

Adds a standard (built-in) signature handler to the signature manager. This method will use cryptographic algorithm based on Adobe.PPKLite/adbe.pkcs7.detached filter to sign a PDF.

Parameters:

• pkcs12_file – The private key certificate store to use.

• pkcs12_pass – The passphrase for the provided private key.

Return type:

int

Returns:

A unique ID representing the SignatureHandler within the SignatureManager.

Overload 2:

Adds a standard (built-in) signature handler to the signature manager. This method will use cryptographic algorithm based on Adobe.PPKLite/adbe.pkcs7.detached filter to sign a PDF.

Parameters:

• pkcs12_keybuffer (std::vector< unsigned char,std::allocator< unsigned char > >) – The private key certificate store to use (as a data buffer in an array of bytes).

• pkcs12_pass – The passphrase for the provided private key.

Return type:

int

Returns:

A unique ID representing the SignatureHandler within the SignatureManager.

AppendTextDiff(args)

Overload 1:

Imports two external pages and highlights the differences between them. This function adds two new pages to the current document. The two input pages are typically coming from two different PDF files. Note: Each contiguous block of change is considered a single difference. A deletion immediately followed by an insertion is considered a single edit.

Parameters:

• page1 (Page) – is the before page, the basis of the comparison (read-only)

• page2 (Page) – is the after page, to which the basis is compared (read-only)

Return type:

int

Returns:

the total number of differences found

Overload 2:

Imports two external PDFs and highlights the differences between them. This function appends alternating pages from the two input documents into the current document. Note: Each contiguous block of change is considered a single difference. A deletion immediately followed by an insertion is considered a single edit.

Parameters:

• doc1 (PDFDoc) – is the before document, the basis of the comparison (read-only)

• doc2 (PDFDoc) – is the after document, to which the basis is compared (read-only)

Return type:

int

Returns:

the total number of differences found

Overload 3:

Imports two external PDFs and highlights the differences between them. This function appends alternating pages from the two input documents into the current document. Note: Each contiguous block of change is considered a single difference. A deletion immediately followed by an insertion is considered a single edit.

Parameters:

• doc1 (PDFDoc) – is the before document, the basis of the comparison (read-only)

• doc2 (PDFDoc) – is the after document, to which the basis is compared (read-only)

• options (TextDiffOptions) – processing options (optional)

Return type:

int

Returns:

the total number of differences found

AppendVisualDiff(p1, p2, opts)

Generates a PDF diff of the given pages by overlaying and blending them on top of each other.

Parameters:

• p1 (Page) – one of the two pages for comparing.

• p2 (Page) – the other page for comparing.

• opts (DiffOptions) – options for comparison results.

Close()

Close PDFDoc

CreateDigitalSignatureField(args)

Creates an unsigned digital signature form field inside the document.

Parameters:

in_sig_field_name (string) – The fully-qualified name to give the digital signature field. If one is not provided, a unique name is created automatically.

Return type:

DigitalSignatureField

Returns:

A DigitalSignatureField object representing the created digital signature field.

CreateIndirectArray()

This method creates an SDF/Cos indirect array object

Unlike direct objects, indirect objects can be referenced by more than one object (i.e. indirect objects can be shared).

Return type:

Obj

Returns:

Returns a new indirect array object.

CreateIndirectBool(value)

This method creates an SDF/Cos indirect boolean object

Unlike direct objects, indirect objects can be referenced by more than one object (i.e. indirect objects can be shared).

Return type:

Obj

Returns:

Returns a new indirect boolean object.

Parameters:

value (boolean) – the value with which to create the boolean object.

CreateIndirectDict()

This method creates an SDF/Cos indirect dict object

Unlike direct objects, indirect objects can be referenced by more than one object (i.e. indirect objects can be shared).

Return type:

Obj

Returns:

Returns a new indirect dict object.

CreateIndirectName(name)

This method creates an SDF/Cos indirect name object

Unlike direct objects, indirect objects can be referenced by more than one object (i.e. indirect objects can be shared).

CreateIndirectNull()

This method creates an SDF/Cos indirect null object

Unlike direct objects, indirect objects can be referenced by more than one object (i.e. indirect objects can be shared).

Return type:

Obj

Returns:

Returns a new indirect null object.

CreateIndirectNumber(value)

This method creates an SDF/Cos indirect number object

Unlike direct objects, indirect objects can be referenced by more than one object (i.e. indirect objects can be shared).

Return type:

Obj

Returns:

Returns a new indirect number object.

Parameters:

value (double) – the value with which to create the number object.

CreateIndirectStream(args)

Overload 1:

This method creates an SDF/Cos indirect stream object

Unlike direct objects, indirect objects can be referenced by more than one object (i.e. indirect objects can be shared).

Return type:

Obj

Returns:

Returns a new indirect stream object.

Parameters:

• data (FilterReader) – reference to a FilterReader object with which to create the stream object.

• filter_chain (Filter) – filter object with which to create the stream object. Defaults to Filters::Filter(0,false)

Overload 2:

This method creates an SDF/Cos indirect stream object

Unlike direct objects, indirect objects can be referenced by more than one object (i.e. indirect objects can be shared).

Return type:

Obj

Returns:

Returns a new indirect stream object.

Parameters:

• data (string) – a buffer from which to create the stream object.

• data_size (int) – size of the buffer.

• filter_chain (Filter) – filter object with which to create the stream object. Defaults to Filters::Filter(0,false)

Overload 3:

This method creates an SDF/Cos indirect stream object

Unlike direct objects, indirect objects can be referenced by more than one object (i.e. indirect objects can be shared).

Return type:

Obj

Returns:

Returns a new indirect stream object.

Parameters:

• data (string) – a buffer from which to create the stream object.

• data_size (int) – size of the buffer.

• filter_chain – filter object with which to create the stream object. Defaults to Filters::Filter(0,false)

CreateIndirectString(args)

Overload 1:

This method creates an SDF/Cos indirect string object

Unlike direct objects, indirect objects can be referenced by more than one object (i.e. indirect objects can be shared).

Return type:

Obj

Returns:

Returns a new indirect string object.

Parameters:

• value (UChar) – Unsigned char pointer with which to create the string object.

• size (int) – length of string.

Overload 2:

This method creates an SDF/Cos indirect string object

Unlike direct objects, indirect objects can be referenced by more than one object (i.e. indirect objects can be shared).

Return type:

Obj

Returns:

Returns a new indirect string object.

Parameters:

str (string) – reference to string with which to create the string object.

static CreateInternal(impl)

FDFExtract(args)

Overload 1:

Extract form data and/or annotations to FDF

Parameters:

flag (int) –

• specifies extract options

Return type:

FDFDoc

Returns:

a pointer to the newly created FDF file with an interactive data.

Overload 2:

Extract form data and/or annotations to FDF

Parameters:

• pages_to_extract (PageSet) – The set of pages for which to extract interactive data.

• flag (int) – specifies extract options

Return type:

FDFDoc

Returns:

a pointer to the newly created FDF file with an interactive data.

Overload 3:

Extract form data and/or annotations to FDF

Parameters:

• pages_to_extract (PageSet) – The set of pages for which to extract interactive data.

• flag – specifies extract options

Return type:

FDFDoc

Returns:

a pointer to the newly created FDF file with an interactive data.

Overload 4:

Extract selected annotations to FDF

Parameters:

annotations (std::vector< PDF::Annot,std::allocator< PDF::Annot > >) – the annotation(s) to extract

Return type:

FDFDoc

Returns:

a pointer to the newly created FDF file with the interactive data.

Overload 5:

Extract annotations to FDF

Parameters:

• annot_added (std::vector< PDF::Annot,std::allocator< PDF::Annot > >) – specifies the array of added annotations

• annot_modified (std::vector< PDF::Annot,std::allocator< PDF::Annot > >) – specifies the array of modified annotations

• annot_deleted (std::vector< PDF::Annot,std::allocator< PDF::Annot > >) – specifies the array of deleted annotations

Return type:

FDFDoc

Returns:

a pointer to the newly created FDF file with an interactive data.

FDFMerge(fdf_doc)

Import form data from FDF file to PDF interactive form.

Parameters:

fdf_doc (FDFDoc) – a reference to the FDF file

FDFUpdate(fdf_doc)

Replace existing form and annotation data with those imported from the FDF file. It will make annotations in the FDF match those in the PDF. Since this method avoids updating annotations unnecessarily it works well with incremental save and can sometimes preserve annotation appearances, but it requires that the annotations intended to be in the final document be in the provided FDF file. Notes: Some PDF viewers (like Chrome) cannot display annotations that don’t already have an appearance, so it is often desirable to call PDFDoc.RefreshAnnotAppearances after this method to ensure these annotations can still be displayed in those applications. This method is not suitable for realtime collaboration.

Parameters:

fdf_doc (FDFDoc) – a pointer to the FDF file

FieldCreate(args)

Overload 1:

Create a new interactive form Field.

Parameters:

• field_name (string) – a string representing the fully qualified name of the field (e.g. “employee.name.first”). field_name must be either a unique name or equal to an existing terminal field name.

• type (int) – field type (e.g. Field::e_text, Field::e_button, etc.)

• field_value (Obj) –

• def_field_value (Obj) –

Return type:

Field

Returns:

the new form Field.

Raises:

if ‘field_name’ is equal to an existing non-terminal field name an exception is thrown.

Overload 2:

Create a new interactive form Field.

Parameters:

• field_name (string) – a string representing the fully qualified name of the field (e.g. “employee.name.first”). field_name must be either a unique name or equal to an existing terminal field name.

• type (int) – field type (e.g. Field::e_text, Field::e_button, etc.)

• field_value (string) –

• def_field_value (string) –

Return type:

Field

Returns:

the new form Field.

Raises:

if ‘field_name’ is equal to an existing non-terminal field name an exception is thrown.

Overload 3:

Create a new interactive form Field.

Parameters:

• field_name (string) – a string representing the fully qualified name of the field (e.g. “employee.name.first”). field_name must be either a unique name or equal to an existing terminal field name.

• type (int) – field type (e.g. Field::e_text, Field::e_button, etc.)

• field_value (string) –

• def_field_value –

Return type:

Field

Returns:

the new form Field.

Raises:

if ‘field_name’ is equal to an existing non-terminal field name an exception is thrown.

FlattenAnnotations(forms_only=False)

Flatten all annotations in the document.

Parameters:

forms_only (boolean) – if false flatten all annotations, otherwise flatten only form fields.

GenerateThumbnails(size)

Generates thumbnail images for all the pages in this PDF document.

Parameters:

size (int) – The maximum dimension (width or height) that thumbnails will have.

GetAcroForm()

Return type:

Obj

Returns:

the AcroForm dictionary located in “/Root” or NULL if dictionary is not present.

GetDigitalSignatureFieldIterator()

Retrieves an iterator that iterates over digital signature fields.

Return type:

DigitalSignatureFieldIterator

Returns:

An iterator that iterates over digital signature fields.

GetDigitalSignaturePermissions()

Retrieves the most restrictive document permissions locking level from all of the signed digital signatures in the document.

Return type:

int

Returns:

An enumerated value representing the most restrictive document permission level found in the document.

GetDocInfo()

Return type:

PDFDocInfo

Returns:

The class representing document information metadata. (i.e. entries in the document information dictionary).

GetDownloadedByteCount()

Returns the number of bytes that have been downloaded, when HasDownloader() is True.

Return type:

int

Returns:

The number bytes downloaded.

Raises:

if ‘HasDownloader()` returns False, calling this method will result in an exception.

GetField(field_name)

Parameters:

field_name (string) –

• a string representing the fully qualified name of

the field (e.g. “employee.name.first”).

Return type:

Field

Returns:

a FieldIterator referring to an interactive Field or to invalid field if the field name was not found. If a given field name was not found itr.HasNext() will return false. For example:

FieldIterator itr = pdfdoc.GetFieldIterator("name");
if (itr.HasNext()) {
  Console.WriteLine("Field name: {0}", itr.Current().GetName());
}
else { ...field was not found... }

GetFieldIterator(args)

Overload 1:

An interactive form (sometimes referred to as an AcroForm) is a collection of fields for gathering information interactively from the user. A PDF document may contain any number of fields appearing on any combination of pages, all of which make up a single, global interactive form spanning the entire document.

The following methods are used to access and manipulate Interactive form fields (sometimes referred to as AcroForms).

Return type:

FieldIterator

Returns:

an iterator to the first Field in the document.

The list of all Fields present in the document can be traversed as follows:

FieldIterator itr = pdfdoc.GetFieldIterator();
for(; itr.HasNext(); itr.Next()) {
  Field field = itr.Current();
  Console.WriteLine("Field name: {0}", field.GetName());
 }

For a sample, please refer to ‘InteractiveForms’ sample project.

Overload 2:

An interactive form (sometimes referred to as an AcroForm) is a collection of fields for gathering information interactively from the user. A PDF document may contain any number of fields appearing on any combination of pages, all of which make up a single, global interactive form spanning the entire document.

The following methods are used to access and manipulate Interactive form fields (sometimes referred to as AcroForms).

Parameters:

field_name (string) – String representing the name of the field to get.

Return type:

FieldIterator

Returns:

an iterator to the Field in the document.

For a sample, please refer to ‘InteractiveForms’ sample project.

GetFileName()

Return type:

string

Returns:

The filename of the document if the document is loaded from disk, or empty string if the document is not yet saved or is loaded from a memory buffer.

GetFirstBookmark()

Return type:

Bookmark

Returns:

• the first Bookmark from the document’s outline tree. If the

Bookmark tree is empty the underlying SDF/Cos Object is null and returned Bookmark is not valid (i.e. Bookmark::IsValid() returns false).

GetHandleInternal()

GetOCGConfig()

Return type:

Config

Returns:

the default optional-content configuration for the document from the OCProperties D entry.

GetOCGs()

Return type:

Obj

Returns:

the Obj array that contains optional-content groups (OCGs) for the document, or NULL if the document does not contain any OCGs. The order of the groups is not guaranteed to be the creation order, and is not the same as the display order.

GetOpenAction()

Return type:

Action

Returns:

Action that is triggered when the document is opened. The returned action can be either a destination or some other kind of Action (see Section 8.5, ‘Actions’ in PDF Reference Manual).

Notes: if the document does not nave associated action the returned Action will be null (i.e. Action.IsValid() returns false)

GetPage(page_number)

Parameters:

page_number (int) –

• the page number in document’s page sequence. Page numbers

in document’s page sequence are indexed from 1.

Return type:

Page

Returns:

a Page corresponding to a given page number, or null (invalid page) if the document does not contain the given page number.

For example:

Page page = pdfdoc.GetPage(page_num);
if (page == null) return; //  Page not found

GetPageCount()

Return type:

int

Returns:

the number of pages in the document.

GetPageIterator(page_number=1)

Use the Next() method on the returned iterator to traverse all pages in the document. For example:

PageIterator itr = pdfdoc.GetPageIterator();
while (itr.HasNext()) { //  Read every page
   Page page = itr.Current();
   // ...
   itr.Next()
}

For full sample code, please take a look at ElementReader, PDFPageTest and PDFDraw sample projects.

Return type:

PageIterator

Returns:

an iterator to the first page in the document.

Parameters:

page_number (int) – page to set the iterator on. 1 corresponds to the first page.

GetPageLabel(page_num)

Return type:

PageLabel

Returns:

the PageLabel that is in effect for the given page. If there is no label object in effect, this method returns an invalid page label object.

Parameters:

page_num (int) – The page number. Because PDFNet indexes pages starting from 1, page_num must be larger than 0.

GetPages()

Return type:

Obj

Returns:

• A dictionary representing the root of the low level page-tree

GetRoot()

Return type:

Obj

Returns:

• A dictionary representing the Cos root of the document (/Root entry

within the trailer dictionary)

GetSDFDoc()

Return type:

SDFDoc

Returns:

document’s SDF/Cos document

GetSecurityHandler()

Return type:

SecurityHandler

Returns:

Currently selected SecurityHandler.

Notes: InitSecurityHandler() should be called before GetSecurityHandler() in order to initialize the handler.

Returned security handler can be modified in order to change the security settings of the existing document. Changes to the current handler will not invalidate the access to the original file and will take effect during document Save().

If the security handler is modified, document will perform a full save even if e_incremental was given as a flag in Save() method.

GetSignatureHandler(signature_handler_id)

Gets the associated signature handler instance from the signature manager by looking it up with the handler name.

Parameters:

signature_handler_id (int) – The unique id of the signature handler to get.

Return type:

SignatureHandler

Returns:

The signature handler instance if found, otherwise NULL.

GetStructTree()

Return type:

STree

Returns:

The document’s logical structure tree root.

GetTotalRemoteByteCount()

Returns the document’s total size in bytes, when HasDownloader() is True.

Return type:

int

Returns:

The total number of bytes in the remote document.

Raises:

if ‘HasDownloader()` returns False, calling this method will result in an exception.

GetTrailer()

Return type:

Obj

Returns:

• A dictionary representing the Cos root of the document (document’s trailer)

GetTriggerAction(trigger)

Get the Action associated with the selected Doc Trigger event.

Parameters:

trigger (int) – the type of trigger event to get

Return type:

Obj

Returns:

the Action Obj if present, otherwise NULL

GetUndoManager()

Return type:

UndoManager

Returns:

The UndoManager object (one-to-one mapped to document)

GetViewPrefs()

Return type:

PDFDocViewPrefs

Returns:

Viewer preferences for this document.

PDFDocViewPrefs is a high-level utility class that can be used to control the way the document is to be presented on the screen or in print.

HasDownloader()

Indicates whether this document was created via the PDFViewCtrl method OpenURLAsync.

Return type:

boolean

Returns:

True if the document was created via the PDFViewCtrl method OpenURLAsync; False otherwise.

HasOC()

Return type:

boolean

Returns:

true if the optional content (OC) feature is associated with the document. The document is considered to have optional content if there is an OCProperties dictionary in the document’s catalog, and that dictionary has one or more entries in the OCGs array.

HasRepairedXRef()

Checks whether or not the underlying file has an XRef table that had to be repaired when the file was opened. If the document had an invalid XRef table when opened, PDFNet will have repaired the XRef table for its working representation of the document.

Return type:

boolean

Returns:

• true if document was found to be corrupted, and was repaired, during

opening and has not been saved since.

Notes: - If this function returns true, it is not possible to incrementally save the document (see http://www.pdftron.com/kb_corrupt_xref)

HasSignatures()

Indicates whether this documents contains any digital signatures.

Return type:

boolean

Returns:

True if a digital signature is found in this PDFDoc.

static HighlightTextDiff(doc1, doc2, options)

Imports two external PDFs and highlights the differences between them. This function directly adds the highlights to the two input documents. Note: Each contiguous block of change is considered a single difference. A deletion immediately followed by an insertion is considered a single edit.

Parameters:

• doc1 (PDFDoc) – is the before document, the basis of the comparison

• doc2 (PDFDoc) – is the after document, to which the basis is compared

• options (TextDiffOptions) – processing options (optional)

Return type:

int

Returns:

the total number of differences found

ImportPages(pages, import_bookmarks=False)

The function imports a list of pages to this document. Although a list of pages can be imported using repeated calls to PageInsert(), PageImport will not import duplicate copies of resources that are shared across pages (such as fonts, images, colorspaces etc). Therefore this method is recommended when a page import list consists of several pages that share the same resources.

Parameters:

• pages (std::vector< PDF::Page,std::allocator< PDF::Page > >) – A list of pages to import. All pages should belong to the same source document.

• import_bookmarks (boolean) – An optional flag specifying whether any bookmark items pointing to pages in the import list should be merged with the target (i.e. this) document.

Return type:

std::vector< PDF::Page,std::allocator< PDF::Page > >

Returns:

a list of imported pages. Note that imported pages are not placed in the document page sequence. This can be done using methods such as PageInsert(), PagePushBack(), etc.

InitSecurityHandler()

Initializes document’s SecurityHandler. This version of InitSecurityHandler() works with Standard and Custom PDF security and can be used in situations where the password is obtained dynamically via user feedback. See EncTest sample for example code.

This function should be called immediately after an encrypted document is opened. The function does not have any side effects on documents that are not encrypted.

If the security handler was successfully initialized it can be later obtained using GetSecurityHandler() method.

Raises:

An exception is thrown if the matching handler for document’s security was not found in the global SecurityManager. In this case, you need to register additional custom security handlers with the global SecurityManager (using SecurityManagerSingleton).

Return type:

boolean

Returns:

true if the SecurityHandler was successfully initialized (this may include authentication data collection, verification etc.), false otherwise.

Parameters:

custom_data – An optional parameter used to specify custom data that should be passed in SecurityHandler::Initialize() callback.

InitStdSecurityHandler(args)

Overload 1:

Initializes document’s SecurityHandler using the supplied password. This version of InitSecurityHandler() assumes that document uses Standard security and that a password is specified directly.

This function should be called immediately after an encrypted document is opened. The function does not have any side effects on documents that are not encrypted.

If the security handler was successfully initialized, it can be later obtained using GetSecurityHandler() method.

Return type:

boolean

Returns:

true if the given password successfully unlocked the document, false otherwise.

Raises:

An exception is thrown if the document’s security Filter is not ‘Standard’. In this case, you need to register additional custom security handlers with the global SecurityManager (SecurityManagerSingleton).

Parameters:

• password (string) – Specifies the password used to open the document without any user feedback. If you would like to dynamically obtain the password, you need to derive a custom class from StdSecurityHandler() and use InitSecurityHandler() without any parameters. See EncTest sample for example code.

• password_sz (int) – An optional parameter used to specify the size of the password buffer, in bytes. If the ‘password_sz’ is 0, or if the parameter is not specified, the function assumes that the string is null terminated.

Remarks: Deprecated. Use versions that accepts UString or buffer instead.

Overload 2:

Initializes document’s SecurityHandler using the supplied password. This version of InitSecurityHandler() assumes that document uses Standard security and that a password is specified directly.

This function should be called immediately after an encrypted document is opened. The function does not have any side effects on documents that are not encrypted.

If the security handler was successfully initialized, it can be later obtained using GetSecurityHandler() method.

Parameters:

password (string) – Specifies the password used to open the document without any user feedback. If you would like to dynamically obtain the password, you need to derive a custom class from StdSecurityHandler() and use InitSecurityHandler() without any parameters. See EncTest sample for example code.

Return type:

boolean

Returns:

true if the given password successfully unlocked the document, false otherwise.

Raises:

An exception is thrown if the document’s security Filter is not ‘Standard’. In this case, you need to register additional custom security handlers with the global SecurityManager (SecurityManagerSingleton).

Overload 3:

Initializes document’s SecurityHandler using the supplied password. This version of InitSecurityHandler() assumes that document uses Standard security and that a password is specified directly.

This function should be called immediately after an encrypted document is opened. The function does not have any side effects on documents that are not encrypted.

If the security handler was successfully initialized, it can be later obtained using GetSecurityHandler() method.

Parameters:

password_buf (std::vector< int,std::allocator< int > >) – Specifies the password used to open the document without any user feedback. If you would like to dynamically obtain the password, you need to derive a custom class from StdSecurityHandler() and use InitSecurityHandler() without any parameters. See EncTest sample for example code.

Return type:

boolean

Returns:

true if the given password successfully unlocked the document, false otherwise.

Raises:

An exception is thrown if the document’s security Filter is not ‘Standard’. In this case, you need to register additional custom security handlers with the global SecurityManager (SecurityManagerSingleton).

InsertPages(args)

Overload 1:

Inserts a range of pages from specified PDFDoc

Parameters:

• insert_before_page_number (int) –

  • the destination of the insertion. If less than or equal to 1,

  the pages are added to the beginning of the document. If larger than the number of pages in the destination document, the pages are appended to the document.

• src_doc (PDFDoc) –

  • source PDFDoc to insert from

• start_page (int) –

  • start of the page number to insert

• end_page (int) –

  • end of the page number to insert

• flag (int) –

  • specifies insert options

• progress –

  • A pointer to the progress interface. NULL if progress tracking is not required.

Overload 2:

Inserts a range of pages from specified PDFDoc using PageSet

Parameters:

• insert_before_page_number (int) –

  • the destination of the insertion. If less than or equal to 1,

  the pages are added to the beginning of the document. If larger than the number of pages in the destination document, the pages are appended to the document.

• src_doc (PDFDoc) –

  • source PDFDoc to insert from

• source_page_set (PageSet) –

  • a collection of the page number to insert

• flag (int) –

  • specifies insert options

• progress –

  • A pointer to the progress interface. NULL if progress tracking is not required.

IsEncrypted()

Return type:

boolean

Returns:

true if the document is/was originally encrypted false otherwise.

IsLinearized()

Call this function to determine whether the document is represented in linearized (fast web view) format.

Return type:

boolean

Returns:

• true if document is stored in fast web view format, false otherwise.

Notes: any changes to the document can invalidate linearization. The function will return ‘true’ only if the original document is linearized and if it is not modified.

In order to provide good performance over relatively slow communication links, PDFNet can generate PDF documents with linearized objects and hint tables that can allow a PDF viewer application to download and view one page of a PDF file at a time, rather than requiring the entire file (including fonts and images) to be downloaded before any of it can be viewed.

To save a document in linearized (fast web view) format you only need to pass ‘Doc.SaveOptions.e_linearized’ flag in the Save method.

IsModified()

Call this function to determine whether the document has been modified since it was last saved.

Return type:

boolean

Returns:

• true if document was modified, false otherwise

IsTagged()

Return type:

boolean

Returns:

true if this document is marked as Tagged PDF, false otherwise.

Lock()

Locks the document to prevent competing threads from accessing the document at the same time. Threads attempting to access the document will wait in suspended state until the thread that owns the lock calls doc.Unlock().

LockRead()

Locks the document to prevent competing write threads (using Lock()) from accessing the document at the same time. Other reader threads however, will be allowed to access the document. Threads attempting to obtain write access to the document will wait in suspended state until the thread that owns the lock calls doc.UnlockRead(). Note: To avoid deadlocks obtaining a write lock while holding a read lock is not permitted and will throw an exception. If this situation is encountered please either unlock the read lock before the write lock is obtained or acquire a write lock (rather than read lock) in the first place.

MergeXFDF(args)

Overload 1:

Merge existing form and annotation data with those imported from the XFDF file. It will replace annotations from pdfdocument with matching annotations from XFDF. In order for the annotations to be considered matching, “name” of the xfdf annotation needs to match “NM” of that in pdf. XFDF annotations that don’t have a match in the pdf document will be added. For regular xfdf files, no deletions will be made This method also supports command form of xfdf, for those files, deletions will be performed for annotations in “delete” section Since this method avoids updating annotations unnecessarily it works well with incremental save. Note: This method is suitable for realtime collaboration.

Parameters:

• stream (Filter) –

  • Input Filter which provides the xfdf contents

• opts (MergeXFDFOptions) –

  • MergeXFDFOptions object for finer control

Raises:

PDFNetException

Overload 2:

Merge existing form and annotation data with those imported from the XFDF file. It will replace annotations from pdfdocument with matching annotations from XFDF. In order for the annotations to be considered matching, “name” of the xfdf annotation needs to match “NM” of that in pdf. XFDF annotations that don’t have a match in the pdf document will be added. For regular xfdf files, no deletions will be made This method also supports command form of xfdf, for those files, deletions will be performed for annotations in “delete” section Since this method avoids updating annotations unnecessarily it works well with incremental save. Note: This method is suitable for realtime collaboration.

Parameters:

• xfdf (string) –

  • xfdf contents in string form or the path to the xfdf file

• opts (MergeXFDFOptions) –

  • MergeXFDFOptions object for finer control

Raises:

PDFNetException

Overload 3:

Merge existing form and annotation data with those imported from the XFDF file. It will replace annotations from pdfdocument with matching annotations from XFDF. In order for the annotations to be considered matching, “name” of the xfdf annotation needs to match “NM” of that in pdf. XFDF annotations that don’t have a match in the pdf document will be added. For regular xfdf files, no deletions will be made This method also supports command form of xfdf, for those files, deletions will be performed for annotations in “delete” section Since this method avoids updating annotations unnecessarily it works well with incremental save. Note: This method is suitable for realtime collaboration.

Parameters:

• xfdf (string) –

  • xfdf contents in string form or the path to the xfdf file

• opts –

  • MergeXFDFOptions object for finer control

Raises:

PDFNetException

MovePages(args)

Overload 1:

Moves a range of pages from specified PDFDoc. Pages are deleted from source document after move.

Parameters:

• move_before_page_number (int) –

  • the destination of the move. If less than or equal to 1,

  the pages are moved to the beginning of the document. If larger than the number of pages in the destination document, the pages are moved to the end of the document.

• src_doc (PDFDoc) –

  • source PDFDoc to move from

• start_page (int) –

  • start of the page number to move

• end_page (int) –

  • end of the page number to move

• flag (int) –

  • specifies insert options

• progress –

  • A pointer to the progress interface. NULL if progress tracking is not required.

Notes: MovePages function does not save src_doc. It merely delete pages in memeory. For permanent changes, PDFDoc::Save should be used to save src_doc after function exists.

Overload 2:

Moves a range of pages from specified PDFDoc. Pages are deleted from source document after move.

Parameters:

• move_before_page_number (int) –

  • the destination of the move. If less than or equal to 1,

  the pages are moved to the beginning of the document. If larger than the number of pages in the destination document, the pages are moved to the end of the document.

• src_doc (PDFDoc) –

  • source PDFDoc to move from

• source_page_set (PageSet) –

  • a collection of the page number to move

• flag (int) –

  • specifies insert options

• progress –

  • A pointer to the progress interface. NULL if progress tracking is not required.

Notes: MovePages function does not save src_doc. It merely delete pages in memeory. For permanent changes, PDFDoc::Save should be used to save src_doc after function exists.

PageCreate(args)

Create a new, empty page in the document. You can use PageWriter to fill the page with new content. Finally the page should be inserted at specific place within document page sequence using PageInsert/PagePushFront/PagePushBack methods.

Return type:

Page

Returns:

A new, empty page.

Notes: the new page still does not belong to document page sequence and should be subsequently placed at a specific location within the sequence.

Parameters:

media_box (Rect) – A rectangle, expressed in default user space units, defining the boundaries of the physical medium on which the page is intended to be displayed or printed. A user space units is 1/72 of an inch. If media_box is not specified the default dimensions of the page are 8.5 x 11 inches (or 8.572, 1172 units).

The following is a listing of some standard U.S. page sizes:

Letter = Rect(0, 0, 612, 792) Legal = Rect(0, 0, 612, 1008) Ledger = Rect(0, 0, 1224, 792) Tabloid = Rect(0, 0, 792, 1224) Executive = Rect(0, 0, 522, 756)

The following is a listing of ISO standard page sizes:

4A0 = Rect(0, 0, 4768, 6741) 2A0 = Rect(0, 0, 3370, 4768) A0 = Rect(0, 0, 2384, 3370) A1 = Rect(0, 0, 1684, 2384) A2 = Rect(0, 0, 1191, 1684) A3 = Rect(0, 0, 842, 1191) A4 = Rect(0, 0, 595, 842) A5 = Rect(0, 0, 420, 595) A6 = Rect(0, 0, 298, 420) A7 = Rect(0, 0, 210, 298) A8 = Rect(0, 0, 147, 210) A9 = Rect(0, 0, 105, 147) A10 = Rect(0, 0, 74, 105) B0 = Rect(0, 0, 2835, 4008) B1 = Rect(0, 0, 2004, 2835) B2 = Rect(0, 0, 1417, 2004) B3 = Rect(0, 0, 1001, 1417) B4 = Rect(0, 0, 709, 1001) B5 = Rect(0, 0, 499, 709) B6 = Rect(0, 0, 354, 499) B7 = Rect(0, 0, 249, 354) B8 = Rect(0, 0, 176, 249) B9 = Rect(0, 0, 125, 176) B10 = Rect(0, 0, 88, 125) C0 = Rect(0, 0, 2599, 3677) C1 = Rect(0, 0, 1837, 2599) C2 = Rect(0, 0, 1298, 1837) C3 = Rect(0, 0, 918, 1298) C4 = Rect(0, 0, 649, 918) C5 = Rect(0, 0, 459, 649) C6 = Rect(0, 0, 323, 459) C7 = Rect(0, 0, 230, 323) C8 = Rect(0, 0, 162, 230) C9 = Rect(0, 0, 113, 162)

C10 = Rect(0, 0, 79, 113)

PageInsert(where, page)

Insert/Import a single page at a specific location in the page sequence.

Parameters:

• where (PageIterator) –

  • The location in the page sequence indicating where to insert

  the page. The page is inserted before the specified location.

• page (Page) –

  • A page to insert.

Notes: Invalidates all PageIterators pointing to the document.

PagePushBack(page)

Adds a page to the end of a document’s page sequence.

Parameters:

page (Page) –

• a page to append to the document

Notes: Invalidates all PageIterators pointing to the document.

PagePushFront(page)

Adds a page to the beginning of a document’s page sequence.

Parameters:

page (Page) –

• a page to prepend to the document

Invalidates all PageIterators pointing to the document.

PageRemove(page_itr)

Parameters:

page_itr (PageIterator) –

• the PageIterator to the page that should be removed

A PageIterator for the given page can be obtained using PDFDoc::GetPageIterator(page_num) or using direct iteration through document’s page sequence.

RefreshAnnotAppearances(options=None)

Generates the appearance stream for annotations in the document using the specified options. A common use case is to generate appearances only for missing annotations, which can be accomplished using the default options.

Parameters:

options (RefreshOptions) – Options that can be used to adjust this generation process.

RefreshFieldAppearances()

Regenerates the appearance stream for every widget annotation in the document Call this method if you modified field’s value and would like to update field’s appearances.

RemovePageLabel(page_num)

Removes the page label that is attached to the specified page, effectively merging the specified range with the previous page label sequence.

Parameters:

page_num (int) – The page from which the page label is removed. Because PDFNet indexes pages starting from 1, page_num must be larger than 0.

RemoveSecurity()

This function removes document security.

RemoveSignatureHandler(signature_handler_id)

Removes a signature handler from the signature manager.

Parameters:

signature_handler_id (int) – The unique id of the signature handler to remove.

Save(args)

Overload 1:

Saves the document to a file.

If a full save is requested to the original path, the file is saved to a file system-determined temporary file, the old file is deleted, and the temporary file is renamed to path.

A full save with remove unused or linearization option may re-arrange object in the cross reference table. Therefore all pointers and references to document objects and resources should be re acquired in order to continue document editing.

In order to use incremental save the specified path must match original path and e_incremental flag bit should be set.

Parameters:

• path (string) –

  • The full path name to which the file is saved.

• flags (int) –

  • A bit field composed of an OR of SDFDoc::SaveOptions values.

Raises:

• if the file can’t be opened for saving or if there is a problem during Save

an Exception object will be thrown.

Notes: - Save will modify the PDFDoc object’s internal representation. As such,

the user should acquire a write lock before calling save.

• If the original pdf has a corrupt xref table (see HasRepairedXref), then

it can not be saved using the e_incremental flag.

Overload 2:

Saves the document to a stream.

Parameters:

• stream (Filter) – The output stream where to write data.

• flags (int) –

  • A bit field composed of an OR of the SDFDoc::SaveOptions values.

Raises:

• if there is a problem during Save an Exception object will be thrown.

Notes: - Save will modify the PDFDoc object’s internal representation. As such,

the user should acquire a write lock before calling save.

• If the original pdf has a corrupt xref table (see HasRepairedXref), then

it can not be saved using the e_incremental flag.

SaveCustomSignature(args)

Overload 1:

Saves a custom signature Contents to a document which has been prepared to receive it. No changes should be made to document in meantime.

Parameters:

• in_signature (std::vector< UChar,std::allocator< UChar > >) – The signature Contents to write

• in_field (DigitalSignatureField) – The signature field to which to write

• in_path (string) – The full path name to which the file is saved.

Raises:

• if there is a problem during Save an Exception object will be thrown.

Overload 2:

Saves a custom signature Contents to a document which has been prepared to receive it. No changes should be made to document in meantime.

Parameters:

• in_signature (std::vector< UChar,std::allocator< UChar > >) – The signature Contents to write

• in_field (DigitalSignatureField) – The signature field to which to write

• out_stream (Filter) – The output stream where to write data.

Raises:

• if there is a problem during Save an Exception object will be thrown.

SaveViewerOptimized(args)

Overload 1:

Applies optimizations to improve viewing speed and saves the document to the specified file. The main optimizations used are linearization and embedding thumbnails for the first page and any complex pages.

Parameters:

• path (string) – The full path name to which the file is saved.

• opts (ViewerOptimizedOptions) – The optimization options

Raises:

if the file can’t be opened for saving or if there is a problem during Save an Exception object will be thrown.

Overload 2:

Applies optimizations to improve viewing speed and saves the document to a memory buffer. The main optimizations used are linearization and embedding thumbnails for the first page and any other pages that are slow to render.

Parameters:

• out_buf (string) – a pointer to the buffer containing the serialized version of the document. (C++ Note) The buffer is owned by a document and the client doesn’t need to do any initialization or cleanup.

• out_buf_size (int) – the size of the serialized document (i.e. out_buf) in bytes.

• opts (ViewerOptimizedOptions) –

  • The optimization options

Raises:

• if the file can’t be opened for saving or if there is a problem during Save

an Exception object will be thrown.

SetOpenAction(action)

Sets the Action that will be triggered when the document is opened.

Parameters:

action (Action) – A new Action that will be triggered when the document is opened. An example of such action is a GoTo Action that takes the user to a given location in the document.

SetPageLabel(page_num, label)

Attaches a label to a page. This establishes the numbering scheme for that page and all following it, until another page label is encountered. This label allows PDF producers to define a page numbering system other than the default.

Parameters:

page_num (int) – The number of the page to label. If page_num is less than 1 or greater than the number of pages in the document, the method does nothing.

SetSecurityHandler(handler)

The function sets a new SecurityHandler as the current security handler.

Parameters:

handler (SecurityHandler) – new SecurityHandler

Notes: Setting a new security handler will not invalidate the access to the original file and will take effect during document Save().

If the security handler is modified, document will perform a full save even if e_incremental was given as a flag in Save() method.

TryLock(milliseconds=0)

Try locking the document, waiting no longer than specified number of milliseconds.

Parameters:

milliseconds (int) –

• max number of milliseconds to wait for the document to lock

Return type:

boolean

Returns:

true if the document is locked for multi-threaded access, false otherwise.

TryLockRead(milliseconds=0)

Tries to obtain a read lock the document for <milliseconds> duration, and returns true if the lock was successfully acquired

Parameters:

milliseconds (int) – duration to obtain a read lock for.

Return type:

boolean

Returns:

true if the document is locked for multi-threaded access, false otherwise.

Unlock()

Removes the lock from the document.

UnlockRead()

Removes the read lock from the document.

VerifySignedDigitalSignatures(in_opts)

Attempts to verify all signed cryptographic digital signatures in the document, ignoring unsigned signatures.

Return type:

int

Returns:

an enumeration value representing the state of the document’s signatures

e_action_trigger_doc_did_print = 21

e_action_trigger_doc_did_save = 19

e_action_trigger_doc_will_close = 17

e_action_trigger_doc_will_print = 20

e_action_trigger_doc_will_save = 18

e_annots_only = 1

e_annots_only_no_links = 5

e_both = 2

e_failure = 1

e_forms_only = 0

e_insert_bookmark = 1

e_insert_goto_bookmark = 2

e_none = 0

e_unsigned = 0

e_unsupported = 3

e_untrusted = 2

e_verified = 4

property mp_doc

property thisown

The membership flag

class apryse_sdk.PDFDocInfo(args)

Bases: object

PDFDocInfo is a high-level utility class that can be used to read and modify document’s metadata.

GetAuthor()

Return type:

string

Returns:

The name of the person who created the document.

GetAuthorObj()

Return type:

Obj

Returns:

SDF/Cos string object representing document’s author.

GetCreationDate()

Return type:

Date

Returns:

The date and time the document was created, in human-readable form.

GetCreator()

Return type:

string

Returns:

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.

GetCreatorObj()

Return type:

Obj

Returns:

SDF/Cos string object representing document’s creator.

GetKeywords()

Return type:

string

Returns:

Keywords associated with the document.

GetKeywordsObj()

Return type:

Obj

Returns:

SDF/Cos string object representing document’s keywords.

GetModDate()

Return type:

Date

Returns:

The date and time the document was most recently modified, in human-readable form.

GetProducer()

Return type:

string

Returns:

If the document was converted to PDF from another format, the name of the application (for example, Distiller) that converted it to PDF.

GetProducerObj()

Return type:

Obj

Returns:

SDF/Cos string object representing document’s producer.

GetSDFObj()

Return type:

Obj

Returns:

document’s SDF/Cos ‘Info’ dictionary or NULL if the info dictionary is not available.

GetSubject()

Return type:

string

Returns:

The subject of the document.

GetSubjectObj()

Return type:

Obj

Returns:

SDF/Cos string object representing document’s subject.

GetTitle()

Return type:

string

Returns:

The document’s title.

GetTitleObj()

Return type:

Obj

Returns:

SDF/Cos string object representing document’s title.

SetAuthor(author)

Set the author of the document.

Parameters:

author (string) – The name of the person who created the document.

SetCreationDate(creation_date)

Set document’s creation date.

Parameters:

creation_date (Date) – The date and time the document was created.

SetCreator(creator)

Set document’s creator.

Parameters:

creator (string) – The name of the application that created the original document.

SetKeywords(keywords)

Set keywords associated with the document.

Parameters:

keywords (string) – Keywords associated with the document.

SetModDate(mod_date)

Set document’s modification date.

Parameters:

mod_date (Date) – The date and time the document was most recently modified.

SetProducer(producer)

Set document’s producer.

Parameters:

producer (string) – The name of the application that generated PDF.

SetSubject(subject)

Set the subject of the document

Parameters:

subject (string) – The subject of the document.

SetTitle(title)

Set document’s title.

Parameters:

title (string) – New title of the document.

property mp_info

property thisown

The membership flag

class apryse_sdk.PDFDocViewPrefs(args)

Bases: object

PDFDocViewPrefs is a high-level utility class that can be used to control the way the document is to be presented on the screen or in print.

PDFDocViewPrefs class corresponds to PageMode, PageLayout, and ViewerPreferences entries in the document’s catalog. For more details please refer to section 8.1 ‘Viewer Preferences’ in PDF Reference Manual.

GetDirection()

Return type:

boolean

Returns:

true is the predominant reading order for text is left to right, false otherwise. See SetDirection() for more information.

GetLayoutMode()

Return type:

int

Returns:

The value of currently selected PageLayout property.

GetNonFullScreenPageMode()

Return type:

int

Returns:

the PageMode used after exiting full-screen mode.

Notes: This entry is meaningful only if the value of the PageMode is set to e_FullScreen; it is ignored otherwise.

GetPageMode()

Return type:

int

Returns:

The value of currently selected PageMode property.

GetPref(pref)

Return type:

boolean

Returns:

the value of given ViewerPref property.

Parameters:

pref (int) – the ViewerPref property type to query.

GetPrintArea()

Return type:

int

Returns:

the page boundary representing the area of a page to be rendered when printing the document.

GetPrintClip()

Return type:

int

Returns:

the page boundary to which the contents of a page are to be clipped when printing the document.

GetSDFObj()

Return type:

Obj

Returns:

document’s SDF/Cos ‘ViewerPreferences’ dictionary or NULL if the object is not present.

GetViewArea()

Return type:

int

Returns:

the page boundary representing the area of a page to be displayed when viewing the document on the screen.

GetViewClip()

Return type:

int

Returns:

the page boundary to which the contents of a page are to be clipped when viewing the document on the screen.

SetDirection(left_to_right)

Sets the predominant reading order for text.

This flag has no direct effect on the document’s contents or page numbering but can be used to determine the relative positioning of pages when displayed side by side or printed n-up.

Parameters:

left_to_right (boolean) –

• true if the predominant reading

order for text is from left to right and false if it is right to left (including vertical writing systems, such as Chinese, Japanese, and Korean). Default value: left_to_right is true.

SetInitialPage(dest)

A utility method used to set the fist page displayed after the document is opened. This method is equivalent to PDFDoc::SetOpenAction(goto_action).

If OpenAction is not specified the document should be opened to the top of the first page at the default magnification factor.

Parameters:

dest (Destination) – A value specifying the page destination to be displayed when the document is opened.

Example:

Destination dest = Destination::CreateFit(page);
pdfdoc.GetViewPrefs().SetInitialPage(dest);

SetLayoutMode(layout)

Sets PageLayout property and change the value of the PageLayout key in the Catalog dictionary.

Parameters:

mode – New PageLayout setting. Default value is e_SinglePage.

SetNonFullScreenPageMode(mode)

Set the document’s page mode, specifying how to display the document on exiting full-screen mode.

Parameters:

mode (int) – PageMode used after exiting full-screen mode. Default value: e_UseNone.

Notes: This entry is meaningful only if the value of the PageMode is set to e_FullScreen; it is ignored otherwise.

SetPageMode(mode)

Sets PageMode property and change the value of the PageMode key in the Catalog dictionary.

Parameters:

mode (int) – New PageMode setting. Default value is e_UseNone.

SetPref(pref, value)

Sets the value of given ViewerPref property.

Parameters:

• pref (int) – the ViewerPref property type to modify.

• value (boolean) – The new value for the property.

SetPrintArea(box)

Sets the page boundary representing the area of a page to be rendered when printing the document.

Parameters:

box (int) – printing region. The default value is page crop-box.

SetPrintClip(box)

Sets the page boundary to which the contents of a page are to be clipped when printing the document.

Parameters:

box (int) – printing clip region. The default value is page crop-box.

SetViewArea(box)

Sets the page boundary representing the area of a page to be displayed when viewing the document on the screen.

Parameters:

box (int) – page boundary displayed when viewing the document on the screen. By default, PDF viewers will display the crop-box.

SetViewClip(box)

Sets the page boundary to which the contents of a page are to be clipped when viewing the document on the screen.

Parameters:

box (int) – screen clip region. The default value is page crop-box.

e_CenterWindow = 4

e_Default = 0

e_DisplayDocTitle = 5

e_FitWindow = 3

e_FullScreen = 3

e_HideMenubar = 1

e_HideToolbar = 0

e_HideWindowUI = 2

e_OneColumn = 2

e_SinglePage = 1

e_TwoColumnLeft = 3

e_TwoColumnRight = 4

e_TwoPageLeft = 5

e_TwoPageRight = 6

e_UseAttachments = 5

e_UseBookmarks = 2

e_UseNone = 0

e_UseOC = 4

e_UseThumbs = 1

property mp_prefs

property thisown

The membership flag

apryse_sdk.PDFDoc_CreateInternal(impl)

apryse_sdk.PDFDoc_HighlightTextDiff(doc1, doc2, options)

Imports two external PDFs and highlights the differences between them. This function directly adds the highlights to the two input documents. Note: Each contiguous block of change is considered a single difference. A deletion immediately followed by an insertion is considered a single edit.

Parameters:

• doc1 (PDFDoc) – is the before document, the basis of the comparison

• doc2 (PDFDoc) – is the after document, to which the basis is compared

• options (TextDiffOptions) – processing options (optional)

Return type:

int

Returns:

the total number of differences found

class apryse_sdk.PDFDraw(dpi=92)

Bases: object

PDFDraw contains methods for converting PDF pages to images and to Bitmap objects. Utility methods are provided to export PDF pages to various raster formats as well as to convert pages to GDI+ bitmaps for further manipulation or drawing.

Notes: This class is available on all platforms supported by PDFNet.

Destroy()

Frees the native memory of the object.

Export(args)

Overload 1:

A utility method to export the given PDF page to an image file.

Parameters:

• page (Page) – The source PDF page.

• filename (string) –

  • The name of the output image file. The filename should include

  the extension suffix (e.g. ‘c:/output/myimage.png’).

format - The file format of the output image. Currently supported formats are:

• “RAW”RAW format. There are four possibilities:

  e_rgba - if transparent and color page; e_gray_alpha - if transparent and gray page; e_rgb - if opaque and color page; e_gray - if opaque and gray page.

  NOTE that if page is set to be transparent (SetPageTransparent), the output color channels are already multiplied by the alpha channel.

• “BMP” : Bitmap image format (BMP)

• “JPEG” : Joint Photographic Experts Group (JPEG) image format

• “PNG” : 24-bit W3C Portable Network Graphics (PNG) image format

• “PNG8”8-bit, palettized PNG format. The exported file size should be

  smaller than the one generated using “PNG”, possibly at the expense of some image quality.

• “TIFF” : Tag Image File Format (TIFF) image format.

• “TIFF8” : Tag Image File Format (TIFF) image format (with 8-bit palete).

By default, the function exports to PNG.

Parameters:

encoder_params (Obj) –

• An optional SDF dictionary object containing key/value

  pairs representing optional encoder parameters. The following table list possible parameters for corresponding export filters:

  |Parameter/Key |Output Format |Description/Value |Example

  
  

  |Quality |JPEG |The value for compression ‘Quality’ must be a number between 0 and 100

  specifying the tradeoff between compression ratio and loss in image quality. 100 stands for best quality.

  
  

style=”Z-INDEX: 0”hint.PutNumber(“Quality”, 60);

See the Example 2 in PDFDraw sample project.

|Dither |

PNG, PNG8, TIFF or TIFF8.

|A boolean used to enable or disable dithering. Relevent only for when the image

is exported in palettized or monochrome mode.

|hint.PutBool(“Dither”, true);

|ColorSpace |PNG or TIFF for grayscale; TIFF for CMYK; PNG, BMP, JPEG, or TIFF for Separation. |A name object used to select the rendering and export color space. Currently

supported values are “Gray”, “RGB, “CMYK”, and “Separation”. The output image format must support specified color space, otherwise the parameter will be ignored. An example of image format that supports CMYK is TIFF. Image formats that support grayscale are PNG and TIFF. Separation output is supported in either a single N-Channel TIFF, or in separate single-channel files (either PNG, BMP, or JPEG). Output in “Separation” space implies that overprint simulation is on. By default, the image is rendered and exported in RGB color space.</td>

<td>hint.PutName(“ColorSpace”, “CMYK”);</td>

</tr> <tr>

<td>BPC</td> <td>PNG or TIFF.</td> <td>A number used to specify ‘bits per pixel’ in the output file. Currently

supported values are 1 and 8 (default is 8). To export monochrome (1 bit per pixel) image, use 1 as the value of BPC parameter and use TIFF or PNG as the export format for the image. By default, the image is not dithered when BPC is 1. To enable dithering add ‘Dither’ option in the export hint.</td>

<td>hint.PutNumber(“BPC”, 1);</td>

</tr>

</table>

Overload 2:

Export the given PDF page to an image stream.

Parameters:

• page (Page) – The source PDF page.

• stream (Filter) –

  • The output stream.

  format - The output image format. See the overloaded method for details.

• encoder_params (Obj) –

  • Optional encoder parameters. See the overloaded method for details.

Overload 3:

Export the given PDF page to an image stream.

Parameters:

• page (Page) – The source PDF page.

• stream (Filter) –

  • The output stream.

  format - The output image format. See the overloaded method for details.

• encoder_params –

  • Optional encoder parameters. See the overloaded method for details.

Overload 4:

Export the given PDF page to an image stream.

Parameters:

• page (Page) – The source PDF page.

• stream (Filter) –

  • The output stream.

  format - The output image format. See the overloaded method for details.

• encoder_params –

  • Optional encoder parameters. See the overloaded method for details.

GetBitmap(args)

Returns the raw rasterized image data for the given image.

Notes: This method is relatively low-level and is only available in PDFNet for C++. If you are using PDFNet for .NET, you can use the function with the same name that directly returns GDI+ Bitmap.

Return type:

BitmapInfo

Returns:

a pointer to the internal memory buffer containing the rasterized image of the given page. The buffer size is at least ‘out_heightout_stride’ bytes. The pixel data is stored in 8 bit per component, BGRA format by default.

Parameters:

• page (Page) – The source PDF page.

• pix_fmt (int) –

  • Optional parameter used to specify the desired pixel format. The default pixel format is e_bgra.

• demult (boolean) –

  • Specifies if the alpha is de-multiplied from the resulting color components. This

  parameter is only used for e_rgba, e_bgra, e_gray_alpha formats.

GetSeparationBitmaps(page)

Returns a vector of rasterized separations for the given image.

Notes: This method is relatively low-level and is only available in PDFNet for C++. If you are using PDFNet for .NET, you can use the function with the same name that directly returns GDI+ Bitmap.

Return type:

std::vector< PDF::Separation,std::allocator< PDF::Separation > >

Returns:

Separation has a pointer to the internal memory buffer containing the rasterized image of the given page. The buffer size is at least ‘out_heightout_stride’ bytes. The pixel data is stored in 8 bit per component, BGRA format.

Parameters:

page (Page) – The source PDF page.

SetAntiAliasing(enable_aa)

Enable or disable anti-aliasing.

Anti-Aliasing is a technique used to improve the visual quality of images when displaying them on low resolution devices (for example, low DPI computer monitors).

Parameters:

enable_aa (boolean) – if true anti-aliasing will be enabled. Anti-aliasing is enabled by default.

SetCaching(enabled=True)

Enables or disables caching. Caching can improve the rendering performance in cases where the same page will be drawn multiple times.

Parameters:

enabled (boolean) –

• if true PDFRasterizer will cache frequently used graphics objects.

SetClipRect(clip_rect)

clip the render region to the provided rect (in page space)

Parameters:

clip_rect (Rect) – clipping rect. By default, PDFDraw will rasterize the entire page box.

SetColorPostProcessMode(mode)

Set the color post processing transformation. This transform is applied to the rasterized bitmap as the final step in the rasterization process, and is applied directly to the resulting bitmap (disregarding any color space information). Color post processing only supported for RGBA output.

Parameters:

mode (int) – is the specific transform to be applied

SetDPI(dpi)

Sets the output image resolution.

DPI stands for Dots Per Inch. This parameter is used to specify the output image size and quality. A typical screen resolution for monitors these days is 92 DPI, but printers could use 200 DPI or more.

Parameters:

dpi (double) – value to set the image resolution to. Higher value = higher resolution.

Notes: The size of resulting image is a function of DPI and the dimensions of the source PDF page. For example, if DPI is 92 and page is 8 inches wide, the output bitmap will have 928 = 736 pixels per line. If you know the dimensions of the destination bitmap, but don’t care about DPI of the image you can use pdfdraw.SetImageSize() instead.

if you would like to rasterize extremely large bitmaps (e.g. with resolutions of 2000 DPI or more) it is not practical to use PDFDraw directly because of the memory required to store the entire image. In this case, you can use PDFRasterizer directly to generate the rasterized image in stripes or tiles.

SetDefaultPageColor(r, g, b)

Sets the default color of the page backdrop.

By default, the page color is white.

Parameters:

• r (int) – the red component of the page backdrop color.

• g (int) – the green component of the page backdrop color.

• b (int) – the blue component of the page backdrop color.

Notes: Only when the page backdrop is not set to transparent (SetPageTransparent), default page color is used.

SetDrawAnnotations(render_annots)

Enable or disable annotation and forms rendering. By default, all annotations and form fields are rendered.

Parameters:

render_annots (boolean) – True to draw annotations, false otherwise.

SetDrawUIElements(draw_ui_elements)

Enable or disable drawing ui elements. Default is disabled.

Parameters:

draw_ui_elements (boolean) – true to draw ui elements, false otherwise.

SetErrorReportProc(instance)

Sets the error handling function to be called in case an error is encountered during page rendering.

Parameters:

• error_proc – Error handling callback function (or delegate in .NET)

• data – Custom data to be passed as a second parameter to ‘error_proc’.

SetFlipYAxis(flip_y)

Flips the vertical (i.e. Y) axis of the image.

Parameters:

flip_y (boolean) – true to flip the Y axis, false otherwise. For compatibility with most raster formats ‘flip_y’ is true by default.

SetGamma(exp)

Sets the gamma factor used for anti-aliased rendering.

Parameters:

exp (double) – is the exponent value of gamma function. Typical values are in the range from 0.1 to 3.

Gamma correction can be used to improve the quality of anti-aliased image output and can (to some extent) decrease the appearance common anti-aliasing artifacts (such as pixel width lines between polygons).

Notes: Gamma correction is used only in the built-in rasterizer.

SetHighlightFields(highlight_fields)

Enable or disable highlighting form fields. Default is disabled.

Parameters:

highlight_fields (boolean) – true to highlight, false otherwise.

SetImageSize(width, height, preserve_aspect_ratio=True)

SetImageSize can be used instead of SetDPI() to adjust page scaling so that image fits into a buffer of given dimensions.

If this function is used, DPI will be calculated dynamically for each page so that every page fits into the buffer of given dimensions.

Parameters:

• width (int) –

  • The width of the image, in pixels/samples.

• height (int) –

  • The height of the image, in pixels/samples.

• preserve_aspect_ratio (boolean) –

  • True to preserve the aspect ratio, false

  otherwise. By default, preserve_aspect_ratio is true.

SetImageSmoothing(smoothing_enabled=True, hq_image_resampling=False)

Enable or disable image smoothing.

The rasterizer allows a tradeoff between rendering quality and rendering speed. This function can be used to indicate the preference between rendering speed and quality.

Notes: image smoothing option has effect only if the source image has higher resolution that the output resolution of the image on the rasterized page. PDFNet automatically controls at what resolution/zoom factor, ‘image smoothing’ needs to take effect.

Parameters:

• smoothing_enabled (boolean) – True to enable image smoothing, false otherwise.

• hq_image_resampling (boolean) – True to use a higher quality (but slower) smoothing algorithm image smoothing is enabled and hq_image_resampling is false.

SetOCGContext(ctx)

Sets the Optional Content Group (OCG) context that should be used when rendering the page. This function can be used to selectively render optional content (such as PDF layers) based on the states of optional content groups in the given context.

Parameters:

ctx (Context) – Optional Content Group (OCG) context, or NULL if the rasterizer should render all content on the page.

SetOverprint(op)

Enable or disable support for overprint and overprint simulation. Overprint is a device dependent feature and the results will vary depending on the output color space and supported colorants (i.e. CMYK, CMYK+spot, RGB, etc).

By default overprint is only enabled for PDF/X files.

Parameters:

op (int) – e_op_on: always enabled; e_op_off: always disabled; e_op_pdfx_on: enabled for PDF/X files only.

SetPageBox(region)

Selects the page box/region to rasterize.

Parameters:

region (int) – Page box to rasterize. By default, PDFDraw will rasterize page crop box.

SetPageTransparent(is_transparent)

Sets the page color to transparent.

By default, PDFDraw assumes that the page is imposed directly on an opaque white surface. Some applications may need to impose the page on a different backdrop. In this case any pixels that are not covered during rendering will be transparent.

Parameters:

is_transparent (boolean) – If true, page’s backdrop color will be transparent. If false, the page’s backdrop will be a opaque white.

Notes: If page transparency is enabled, the alpha channel will be preserved when the image is exported as PNG, TIFF(when in RGB space), or RAW.

SetPathHinting(enable_hinting)

Enable or disable path hinting.

Parameters:

enable_hinting (boolean) – if true path hinting will be enabled. Path hinting is used to slightly adjust paths in order to avoid or alleviate artifacts of hair line cracks between certain graphical elements. This option is turned on by default.

SetPrintMode(is_printing)

Tells the rasterizer to render the page ‘print’ mode. Certain page elements (such as annotations or OCG-s) are meant to be visible either on the screen or on the printed paper but not both. A common example, is the “Submit” button on electronic forms.

Parameters:

is_printing (boolean) – set to true if the page should be rendered in print mode. By default, print mode flag is set to false.

SetRasterizerType(type)

Sets the core graphics library used for rasterization and rendering. Using this method it is possible to quickly switch between different implementations. By default, PDFDraw uses the built-in, platform independent rasterizer.

Parameters:

type (int) – Rasterizer type.

Notes: This method is deprecated, since the GDI+ rasterizer itself is deprecated and will be removed in a future version of PDFNet. It is strongly recommended to use the built-in rasterizer and to use the XPS print path where vector conversion is needed.

SetRotate(r)

Sets the rotation value for this page.

Notes: This method is used only for drawing purposes and it does not modify the document (unlike Page::SetRotate()).

Parameters:

r (int) – Rotation value to be set for a given page. Must be one of the Page::Rotate values.

SetThinLineAdjustment(pixel_grid_fit, stroke_adjust)

Set thin line adjustment parameters.

Parameters:

• pixel_grid_fit (boolean) – if true (horizontal/vertical) thin lines will be snapped to integer pixel positions. This helps make thin lines look sharper and clearer. This option is turned off by default and it only works if path hinting is enabled.

• stroke_adjust (boolean) – if true auto stroke adjustment is enabled. Currently, this would make lines with sub-pixel width to be one-pixel wide. This option is turned on by default.

SetThinLineScaling(scaling)

This setting controls the thickness of zero-width lines when rendered. In a PDF, a line width of zero denotes the thinnest line that can be rendered at device resolution: 1 device pixel wide. However, on high-resolution devices, a single pixel can be nearly invisible.

Parameters:

scaling (double) – use this setting to increase the apparent thickness of these zero-width lines. 1.0 (1 pixel wide)

e_bgr = 3

e_bgra = 1

e_cmyk = 6

e_gray = 4

e_gray_alpha = 5

e_rgb = 2

e_rgba = 0

property mp_draw

property thisown

The membership flag

class apryse_sdk.PDFNet

Bases: object

PDFNet contains global library initialization, registration, configuration, and termination methods.

Notes: there is only a single, static instance of PDFNet class. Initialization and termination methods need to be called only once per application session.

static AddFontSubst(args)

Overload 1:

AddFontSubst functions can be used to create font substitutes that can override default PDFNet font selection algorithm.

AddFontSubst functions are useful in situations where referenced fonts are not present in the document and PDFNet font substitution algorithm is not producing desired results.

AddFontSubst(fontname, fontpath) maps the given font name (i.e. ‘BaseFont’ entry from the font dictionary) to a font file.

The following is an example of using this function to provide user defined font substitutes:

PDFNet::Initialize();
PDFNet::SetResourcesPath("c:/myapp/resources");
// Specify specific font mappings...
PDFNet::AddFontSubst("MinionPro-Regular", "c:/myfonts/MinionPro-Regular.otf");
PDFNet::AddFontSubst("Times-Roman", "c:/windows/fonts/times.ttf");
PDFNet::AddFontSubst("Times-Italic", "c:/windows/fonts/timesi.ttf");
...
PDFDoc doc("c:/my.pdf");
...

Overload 2:

AddFontSubst functions can be used to create font substitutes that can override default PDFNet font selection algorithm.

AddFontSubst functions are useful in situations where referenced fonts are not present in the document and PDFNet font substitution algorithm is not producing desired results.

AddFontSubst(ordering, fontpath) maps the given character ordering (see Ordering entry in CIDSystemInfo dictionary; Section 5.6.2 in PDF Reference) to a font file. This method is less specific that the former variant of AddFontSubst, and can be used to override a range of missing fonts (or any missing font) with a predefined substitute.

The following is an example of using this function to provide user defined font substitutes:

PDFNet::Initialize();
PDFNet::SetResourcesPath("c:/myapp/resources");

// Specify more general font mappings...
PDFNet::AddFontSubst(PDFNet::e_Identity, "c:/myfonts/arialuni.ttf");  // Arial Unicode MS
PDFNet::AddFontSubst(PDFNet::e_Japan1, "c:/myfonts/KozMinProVI-Regular.otf");
PDFNet::AddFontSubst(PDFNet::e_Japan2, "c:/myfonts/KozMinProVI-Regular.otf");
PDFNet::AddFontSubst(PDFNet::e_Korea1, "c:/myfonts/AdobeSongStd-Light.otf");
PDFNet::AddFontSubst(PDFNet::e_CNS1, "c:/myfonts/AdobeMingStd-Light.otf");
PDFNet::AddFontSubst(PDFNet::e_GB1, "c:/myfonts/AdobeMyungjoStd-Medium.otf");
...
PDFDoc doc("c:/my.pdf");
...

static AddPDFTronCustomHandler(custom_id)

End of conditional comment.

Add PDFTron Custom Security handler

Parameters:

custom_id (int) – The user’s custom id. The id should match what was used to create PDFTronCustomSecurityHandler when encrypting the document.

Notes: calling this function is a requirement to load files encrypted with PDFTronCustomSecurityHandler.

static AddResourceSearchPath(path)

Sets the location of PDFNet resource file.

Notes: Starting with v.4.5 PDFNet no longer requires a seperate resource file, and so this function is not required for proper PDFNet initialization. The function can be used on all platforms to specify search paths for ICC profiles, fonts, and other user defined resources.

Parameters:

path (string) –

• The resource directory path to add to the search list.

static EnableJavaScript(enable)

A switch that can be used to turn on/off JavaScript engine

Parameters:

enable (boolean) – true to enable JavaScript engine, false to disable.

static GetResourcesPath()

Return type:

string

Returns:

the location of PDFNet resources folder. Empty string means that resources are located in your application folder.

static GetSystemFontList()

Get available fonts on the system.

Return type:

string

Returns:

A JSON list of fonts accessible to PDFNet

static GetVersion()

Return type:

double

Returns:

PDFNet version number.

static GetVersionString()

Return type:

string

Returns:

PDFNet version as a string.

static Initialize(args)

static IsJavaScriptEnabled()

Test whether JavaScript is enabled

Return type:

boolean

Returns:

true if it is enabled, false otherwise

static SetColorManagement(args)

Used to set a specific Color Management System (CMS) for use during color conversion operators, image rendering, etc.

Parameters:

t (int) – identifies the type of color management to use.

static SetConnectionErrorHandlingMode(mode)

Sets the connection error handling behaviour for Apryse SDK The default for this method is e_continue

Parameters:

mode (int) – Rules that Apryse SDK will follow after a connection error.

static SetConnectionErrorProc(instance)

Sets the error handling function to be called when an error is encountered when connecting to PDFTron Web Services.

Parameters:

• error_proc – Connection error handling callback function (or delegate in .NET)

• data – Custom data to be passed as the fourth parameter to ‘error_proc’.

static SetDefaultDeviceCMYKProfile(args)

Overload 1:

Sets the default ICC color profile for DeviceCMYK color space.

Notes: You can use this method to override default PDFNet settings. For more information on default color spaces please refer to section ‘Default Color Spaces’ in Chapter 4.5.4 of PDF Reference Manual.

Raises:

the function will throw Exception if the ICC profile can’t be found or if it fails to open.

Overload 2:

Sets the default ICC color profile for DeviceCMYK color space.

Notes: You can use this method to override default PDFNet settings. For more information on default color spaces please refer to section ‘Default Color Spaces’ in Chapter 4.5.4 of PDF Reference Manual.

Raises:

the function will throw Exception if the ICC profile fails to open.

static SetDefaultDeviceRGBProfile(args)

Overload 1:

Sets the default ICC color profile for DeviceRGB color space.

Notes: You can use this method to override default PDFNet settings. For more information on default color spaces please refer to section ‘Default Color Spaces’ in Chapter 4.5.4 of PDF Reference Manual.

Raises:

the function will throw Exception if the ICC profile can’t be found or if it fails to open.

Overload 2:

Sets the default ICC color profile for DeviceRGB color space.

Notes: You can use this method to override default PDFNet settings. For more information on default color spaces please refer to section ‘Default Color Spaces’ in Chapter 4.5.4 of PDF Reference Manual.

Raises:

the function will throw Exception if the ICC profile fails to open.

static SetDefaultDiskCachingEnabled(use_disk)

Sets the default policy on using temporary files.

_disk if parameter is true then new documents are allowed to create temporary files; otherwise all document contents will be stored in memory.

static SetDefaultFlateCompressionLevel(level)

Sets the default compression level for Flate (ZLib).

type level:

int

Parameters:

level –

An integer in range 0-9 representing the compression value to use as a default for any Flate streams (e.g used to compress content streams, PNG images, etc). The library normally uses the default compression level (Z_DEFAULT_COMPRESSION). For most images, compression values in the range 3-6 compress nearly as well as higher levels, and do so much faster. For on-line applications it may be desirable to have maximum speed Z_BEST_SPEED = 1). You can also specify no compression (Z_NO_COMPRESSION = 0).

Z_DEFAULT_COMPRESSION (-1).

static SetLogLevel(args)

static SetPersistentCachePath(persistent_path)

Set the location of persistent cache files.

This method is provided for applications that require tight control of the location where temporary files are created.

static SetResourcesPath(path)

Sets the location of PDFNet resource file.

Notes: Starting with v.4.5 PDFNet no longer requires a seperate resource file, and so this function is not required for proper PDFNet initialization. It remains available for backward compatibility. On mobile systems (iOS, Android, etc.) this method is required for proper initialization starting with version 6.0. (This helps reduce overall app size.) The function can be used on all platforms to specify a default search path for ICC profiles, fonts, and other user defined resources.

Parameters:

path (string) –

• The default resource directory path.

Return type:

boolean

Returns:

true if path is found, false otherwise.

static SetTempPath(temp_path)

Set the location of temporary folder.

This method is provided for applications that require tight control of the location where temporary files are created.

static SetViewerCache(max_cache_size, on_disk)

Sets the default parameters for the viewer cache. Any subsequently created documents

will use these parameters.

type max_cache_size:

int

Parameters:

• max_cache_size –

  • The maximum size, in bytes, of the entire document’s page cache. Set to zero to disable the viewer cache.

  type on_disk:

  boolean

• on_disk –

  • If set to ‘true’, cache will be stored on the local filesystem. If set to ‘false’, cache will be stored in heap memory.

  Desktop: max_cache_size = 512 MB, on_disk = true | Mobile: max_cache_size = 100 MB, on_disk = false

static SetWriteAPIUsageLocally(write_usage)

Enable writing API usage locally.

Parameters:

write_usage (boolean) – if parameter is true API usage will be written to local JSON files in the persistent cache path otherwise no API usage is saved.

static Terminate(args)

e_CNS1 = 4

Chinese; Traditional

e_GB1 = 3

Chinese; Simplified

e_Identity = 0

Generic/Unicode

e_Japan1 = 1

Japanese

e_Japan2 = 2

Japanese

e_Korea1 = 5

Korean

e_LogLevel_Debug = 0

e_LogLevel_Error = 4

e_LogLevel_Fatal = 5

e_LogLevel_Info = 2

e_LogLevel_Off = -1

e_LogLevel_Trace = 1

e_LogLevel_Warning = 3

e_Z_BEST_COMPRESSION = 9

e_Z_BEST_SPEED = 1

e_Z_DEFAULT_COMPRESSION = -1

e_Z_NO_COMPRESSION = 0

e_continue = 0

e_continue_unless_switching_to_demo = 1

e_icm = 1

Use Windows ICM2 (available only on Windows platforms).

e_lcms = 0

Use LittleCMS (available on all supported platforms).

e_no_cms = 2

No ICC color management.

e_stop = 2

property thisown

The membership flag

apryse_sdk.PDFNet_AddFontSubst(args)

Overload 1:

AddFontSubst functions can be used to create font substitutes that can override default PDFNet font selection algorithm.

AddFontSubst functions are useful in situations where referenced fonts are not present in the document and PDFNet font substitution algorithm is not producing desired results.

AddFontSubst(fontname, fontpath) maps the given font name (i.e. ‘BaseFont’ entry from the font dictionary) to a font file.

The following is an example of using this function to provide user defined font substitutes:

PDFNet::Initialize();
PDFNet::SetResourcesPath("c:/myapp/resources");
// Specify specific font mappings...
PDFNet::AddFontSubst("MinionPro-Regular", "c:/myfonts/MinionPro-Regular.otf");
PDFNet::AddFontSubst("Times-Roman", "c:/windows/fonts/times.ttf");
PDFNet::AddFontSubst("Times-Italic", "c:/windows/fonts/timesi.ttf");
...
PDFDoc doc("c:/my.pdf");
...

Overload 2:

AddFontSubst functions can be used to create font substitutes that can override default PDFNet font selection algorithm.

AddFontSubst functions are useful in situations where referenced fonts are not present in the document and PDFNet font substitution algorithm is not producing desired results.

AddFontSubst(ordering, fontpath) maps the given character ordering (see Ordering entry in CIDSystemInfo dictionary; Section 5.6.2 in PDF Reference) to a font file. This method is less specific that the former variant of AddFontSubst, and can be used to override a range of missing fonts (or any missing font) with a predefined substitute.

The following is an example of using this function to provide user defined font substitutes:

PDFNet::Initialize();
PDFNet::SetResourcesPath("c:/myapp/resources");

// Specify more general font mappings...
PDFNet::AddFontSubst(PDFNet::e_Identity, "c:/myfonts/arialuni.ttf");  // Arial Unicode MS
PDFNet::AddFontSubst(PDFNet::e_Japan1, "c:/myfonts/KozMinProVI-Regular.otf");
PDFNet::AddFontSubst(PDFNet::e_Japan2, "c:/myfonts/KozMinProVI-Regular.otf");
PDFNet::AddFontSubst(PDFNet::e_Korea1, "c:/myfonts/AdobeSongStd-Light.otf");
PDFNet::AddFontSubst(PDFNet::e_CNS1, "c:/myfonts/AdobeMingStd-Light.otf");
PDFNet::AddFontSubst(PDFNet::e_GB1, "c:/myfonts/AdobeMyungjoStd-Medium.otf");
...
PDFDoc doc("c:/my.pdf");
...

apryse_sdk.PDFNet_AddPDFTronCustomHandler(custom_id)

End of conditional comment.

Add PDFTron Custom Security handler

Parameters:

custom_id (int) – The user’s custom id. The id should match what was used to create PDFTronCustomSecurityHandler when encrypting the document.

Notes: calling this function is a requirement to load files encrypted with PDFTronCustomSecurityHandler.

apryse_sdk.PDFNet_AddResourceSearchPath(path)

Sets the location of PDFNet resource file.

Notes: Starting with v.4.5 PDFNet no longer requires a seperate resource file, and so this function is not required for proper PDFNet initialization. The function can be used on all platforms to specify search paths for ICC profiles, fonts, and other user defined resources.

Parameters:

path (string) –

• The resource directory path to add to the search list.

apryse_sdk.PDFNet_EnableJavaScript(enable)

A switch that can be used to turn on/off JavaScript engine

Parameters:

enable (boolean) – true to enable JavaScript engine, false to disable.

apryse_sdk.PDFNet_GetResourcesPath()

Return type:

string

Returns:

the location of PDFNet resources folder. Empty string means that resources are located in your application folder.

apryse_sdk.PDFNet_GetSystemFontList()

Get available fonts on the system.

Return type:

string

Returns:

A JSON list of fonts accessible to PDFNet

apryse_sdk.PDFNet_GetVersion()

Return type:

double

Returns:

PDFNet version number.

apryse_sdk.PDFNet_GetVersionString()

Return type:

string

Returns:

PDFNet version as a string.

apryse_sdk.PDFNet_Initialize(args)

apryse_sdk.PDFNet_IsJavaScriptEnabled()

Test whether JavaScript is enabled

Return type:

boolean

Returns:

true if it is enabled, false otherwise

apryse_sdk.PDFNet_SetColorManagement(args)

Used to set a specific Color Management System (CMS) for use during color conversion operators, image rendering, etc.

Parameters:

t (int) – identifies the type of color management to use.

apryse_sdk.PDFNet_SetConnectionErrorHandlingMode(mode)

Sets the connection error handling behaviour for Apryse SDK The default for this method is e_continue

Parameters:

mode (int) – Rules that Apryse SDK will follow after a connection error.

apryse_sdk.PDFNet_SetConnectionErrorProc(instance)

Sets the error handling function to be called when an error is encountered when connecting to PDFTron Web Services.

Parameters:

• error_proc – Connection error handling callback function (or delegate in .NET)

• data – Custom data to be passed as the fourth parameter to ‘error_proc’.

apryse_sdk.PDFNet_SetDefaultDeviceCMYKProfile(args)

Overload 1:

Sets the default ICC color profile for DeviceCMYK color space.

Notes: You can use this method to override default PDFNet settings. For more information on default color spaces please refer to section ‘Default Color Spaces’ in Chapter 4.5.4 of PDF Reference Manual.

Raises:

the function will throw Exception if the ICC profile can’t be found or if it fails to open.

Overload 2:

Sets the default ICC color profile for DeviceCMYK color space.

Notes: You can use this method to override default PDFNet settings. For more information on default color spaces please refer to section ‘Default Color Spaces’ in Chapter 4.5.4 of PDF Reference Manual.

Raises:

the function will throw Exception if the ICC profile fails to open.

apryse_sdk.PDFNet_SetDefaultDeviceRGBProfile(args)

Overload 1:

Sets the default ICC color profile for DeviceRGB color space.

Notes: You can use this method to override default PDFNet settings. For more information on default color spaces please refer to section ‘Default Color Spaces’ in Chapter 4.5.4 of PDF Reference Manual.

Raises:

the function will throw Exception if the ICC profile can’t be found or if it fails to open.

Overload 2:

Sets the default ICC color profile for DeviceRGB color space.

Notes: You can use this method to override default PDFNet settings. For more information on default color spaces please refer to section ‘Default Color Spaces’ in Chapter 4.5.4 of PDF Reference Manual.

Raises:

the function will throw Exception if the ICC profile fails to open.

apryse_sdk.PDFNet_SetDefaultDiskCachingEnabled(use_disk)

Sets the default policy on using temporary files.

_disk if parameter is true then new documents are allowed to create temporary files; otherwise all document contents will be stored in memory.

apryse_sdk.PDFNet_SetDefaultFlateCompressionLevel(level)

Sets the default compression level for Flate (ZLib).

type level:

int

Parameters:

level –

An integer in range 0-9 representing the compression value to use as

a default for any Flate streams (e.g used to compress content streams, PNG images, etc). The library normally uses the default compression level (Z_DEFAULT_COMPRESSION). For most images, compression values in the range 3-6 compress nearly as well as higher levels, and do so much faster. For on-line applications it may be desirable to have maximum speed Z_BEST_SPEED = 1). You can also specify no compression (Z_NO_COMPRESSION = 0).

Z_DEFAULT_COMPRESSION (-1).

apryse_sdk.PDFNet_SetLogLevel(args)

apryse_sdk.PDFNet_SetPersistentCachePath(persistent_path)

Set the location of persistent cache files.

This method is provided for applications that require tight control of the location where temporary files are created.

apryse_sdk.PDFNet_SetResourcesPath(path)

Sets the location of PDFNet resource file.

Notes: Starting with v.4.5 PDFNet no longer requires a seperate resource file, and so this function is not required for proper PDFNet initialization. It remains available for backward compatibility. On mobile systems (iOS, Android, etc.) this method is required for proper initialization starting with version 6.0. (This helps reduce overall app size.) The function can be used on all platforms to specify a default search path for ICC profiles, fonts, and other user defined resources.

Parameters:

path (string) –

• The default resource directory path.

Return type:

boolean

Returns:

true if path is found, false otherwise.

apryse_sdk.PDFNet_SetTempPath(temp_path)

Set the location of temporary folder.

This method is provided for applications that require tight control of the location where temporary files are created.

apryse_sdk.PDFNet_SetViewerCache(max_cache_size, on_disk)

Sets the default parameters for the viewer cache. Any subsequently created documents

will use these parameters.

type max_cache_size:

int

Parameters:

• max_cache_size –

  • The maximum size, in bytes, of the entire document’s page cache. Set to zero to disable the viewer cache.

  type on_disk:

  boolean

• on_disk –

  • If set to ‘true’, cache will be stored on the local filesystem. If set to ‘false’, cache will be stored in heap memory.

  Desktop: max_cache_size = 512 MB, on_disk = true | Mobile: max_cache_size = 100 MB, on_disk = false

apryse_sdk.PDFNet_SetWriteAPIUsageLocally(write_usage)

Enable writing API usage locally.

Parameters:

write_usage (boolean) – if parameter is true API usage will be written to local JSON files in the persistent cache path otherwise no API usage is saved.

apryse_sdk.PDFNet_Terminate(args)

class apryse_sdk.PDFRasterizer(args)

Bases: object

PDFRasterizer is a low-level PDF rasterizer.

The main purpose of this class is to convert PDF pages to raster images (or bitmaps).

Notes: PDFRasterizer is a relatively low-level class. If you need to convert PDF page to an image format or a Bitmap, consider using PDF::PDFDraw. Similarly, if you are building an interactive PDF viewing application you may want to use PDF::PDFView instead.

Destroy()

Frees the native memory of the object.

GetColorPostProcessMode()

Return type:

int

Returns:

the current color post processing mode.

GetRasterizerType()

Return type:

int

Returns:

the type of current rasterizer.

Notes: This method is deprecated, since the GDI+ rasterizer itself is deprecated and will be removed in a future version of PDFNet. It is strongly recommended to use the built-in rasterizer and to use the XPS print path where vector conversion is needed.

Rasterize(page, width, height, stride, num_comps, demult, device_mtx, clip=None, scrl_clip_regions=None)

Draws the page into a given memory buffer.

Notes: This method is available on all platforms and in all rasterizer implementations.

Parameters:

• page (Page) – The page to rasterize.

• in_out_image_buffer – A pointer to a memory buffer. The buffer must contain at least (stride height) bytes.

• width (int) – The width of the target image in pixels.

• height (int) – The height of the target image in pixels (the number of rows).

• stride (int) – Stride determines the physical width (in bytes) of one row in memory. If this value is negative the direction of the Y axis is inverted. The absolute value of stride is of importance, because it allows rendering in buffers where rows are padded in memory (e.g. in Windows bitmaps are padded on 4 byte boundaries). Besides allowing rendering on the whole buffer stride parameter can be used for rendering in a rectangular subset of a buffer.

• num_comps (int) – The number (4 or 5) representing the number of color components in the device color space. For BGR+Alpha set this parameter to 4, and for CMYK+Alpha use 5. If other values are set, exceptions will be thrown.

• demult (boolean) –

  • Specifies if the alpha is de-multiplied from the resulting color components.

• device_mtx (Matrix2D) – Device transformation matrix that maps PDF page from PDF user space into device coordinate space (e.g. pixel space). PDF user space is represented in page units, where one unit corresponds to 1/72 of an inch.

• clip (Rect) – Optional parameter defining the clip region for the page. If the parameter is null or is not specified, PDFRasterizer uses page’s crop box as a default clip region.

• scrl_clp_regions – Optional parameter reserved for a future use.

• cancel – An optional variable that can be used to stop the rendering thread.

Sample code:

double drawing_scale = 2:
Common::Matrix2D mtx(drawing_scale, 0, 0, drawing_scale, 0, 0);
PDF::Rect bbox(page.GetMediaBox());
bbox.Normalize();
int width = int(bbox.Width()  drawing_scale);
int height = int(bbox.Height()  drawing_scale);

// Stride is represented in bytes and is aligned on 4 byte
// boundary so that you can render directly to GDI bitmap.
// A negative value for stride can be used to flip the image
// upside down.
int comps = 4;  // for BGRA
int stride = ((width  comps + 3) / 4)  4;

// buf is a memory buffer containing at least (strideheight) bytes.
   memset(ptr, 0xFF, heightstride);  // Clear the background to opaque white paper color.

PDFRasterizer rast;
rast.Rasterize(page, buf, width, height, stride, 4, false, mtx);

RasterizeSeparations(page, width, height, mtx, clip, cancel)

Draws the page into a given memory buffer.

Notes: This method is available on all platforms and in all rasterizer implementations.

Parameters:

• page (Page) – The page to rasterize.

• width (int) – The width of the target image in pixels.

• height (int) – The height of the target image in pixels (the number of rows).

• mtx (Matrix2D) – Device transformation matrix that maps PDF page from PDF user space into device coordinate space (e.g. pixel space). PDF user space is represented in page units, where one unit corresponds to 1/72 of an inch.

• clip (Rect) – Optional parameter defining the clip region for the page. If the parameter is null or is not specified, PDFRasterizer uses page’s crop box as a default clip region.

• cancel (boolean) – An optional variable that can be used to stop the rendering thread.

SetAntiAliasing(enable_aa)

Enable or disable anti-aliasing.

Anti-Aliasing is a technique used to improve the visual quality of images when displaying them on low resolution devices (for example, low DPI computer monitors).

Anti-aliasing is enabled by default.

SetCaching(enabled=True)

Enables or disables caching. Caching can improve the rendering performance in cases where the same page will be drawn multiple times.

Parameters:

enabled (boolean) –

• if true PDFRasterizer will cache frequently used graphics objects.

SetColorPostProcessMode(mode)

Set the color post processing transformation. This transform is applied to the rasterized bitmap as the final step in the rasterization process, and is applied directly to the resulting bitmap (disregarding any color space information). Color post processing only supported for RGBA output.

Parameters:

mode (int) – is the specific transform to be applied

SetDrawAnnotations(render_annots)

Enable or disable annotation and forms rendering. By default, annotations and forms are rendered.

Parameters:

render_annots (boolean) – True to draw annotations, false otherwise.

SetDrawUIElements(draw_ui_elements)

Enable or disable drawing ui elements. Default is disabled.

Parameters:

draw_ui_elements (boolean) – true to draw ui elements, false otherwise.

SetErrorReportProc(instance)

Sets the error handling function to be called in case an error is encountered during page rendering.

Parameters:

• error_proc – Error handling callback function (or delegate in .NET)

• data – Custom data to be passed as a second parameter to ‘error_proc’.

SetGamma(expgamma)

Sets the gamma factor used for anti-aliased rendering.

Parameters:

expgamma (double) – is the exponent value of gamma function. Typical values are in the range from 0.1 to 3.

Gamma correction can be used to improve the quality of anti-aliased image output and can (to some extent) decrease the appearance common anti-aliasing artifacts (such as pixel width lines between polygons).

Notes: Gamma correction is used only in the built-in rasterizer.

SetHighlightFields(highlight_fields)

Enable or disable highlighting form fields. Default is disabled.

Parameters:

highlight_fields (boolean) – true to highlight, false otherwise.

SetImageSmoothing(smoothing_enabled=True, hq_image_resampling=False)

Enable or disable image smoothing.

The rasterizer allows a tradeoff between rendering quality and rendering speed. This function can be used to indicate the preference between rendering speed and quality.

Notes: image smoothing option has effect only if the source image has higher resolution that the output resolution of the image on the rasterized page. PDFNet automatically controls at what resolution/zoom factor, ‘image smoothing’ needs to take effect.

Parameters:

• smoothing_enabled (boolean) – True to enable image smoothing, false otherwise.

• hq_image_resampling (boolean) – True to use a higher quality (but slower) smoothing algorithm image smoothing is enabled and hq_image_resampling is false.

SetNightModeTuning(contrast, saturation, flipness)

This setting controls the contrast, saturation and flipness of a rendered PDF when night mode is set. By default no additional tuning is done.

Parameters:

• contrast (double) – change the difference in luminance or color that makes an object distinguishable from other objects.

• saturation (double) – change the color intensity.

• flipness (double) – controls the inversion of colors when rendered.

Notes: values range from 0.0 to 1.0

SetOCGContext(ctx)

Sets the Optional Content Group (OCG) context that should be used when

rendering the page. This function can be used to selectively render optional

content (such as PDF layers) based on the states of optional content groups in the given context.

Parameters:

ctx (Context) – Optional Content Group (OCG) context, or NULL if the rasterizer should render all content on the page.

SetOverprint(op)

Enable or disable support for overprint and overprint simulation. Overprint is a device dependent feature and the results will vary depending on the output color space and supported colorants (i.e. CMYK, CMYK+spot, RGB, etc).

By default overprint is only enabled for PDF/X files.

Parameters:

op (int) – e_op_on: always enabled; e_op_off: always disabled; e_op_pdfx_on: enabled for PDF/X files only.

SetPathHinting(enable_hinting)

Enable or disable path hinting.

Parameters:

enable_hinting (boolean) – if true path hinting is enabled. Path hinting is used to slightly adjust paths in order to avoid or alleviate artifacts of hair line cracks between certain graphical elements. This option is turned on by default.

SetPrintMode(is_printing)

Tells the rasterizer to render the page ‘print’ mode. Certain page elements (such as annotations or OCG-s) are meant to be visible either on the screen or on the printed paper but not both. A common example, is the “Submit” button on electronic forms.

Parameters:

is_printing (boolean) – set to true is the page should be rendered in print mode. By default, print mode flag is set to false.

SetRasterizerType(type)

Sets the core graphics library used for rasterization and rendering. Using this method it is possible to quickly switch between different implementations. By default, PDFNet uses a built-in, high-quality, and platform independent rasterizer.

Parameters:

type (int) – Rasterizer type.

Notes: This method is deprecated, since the GDI+ rasterizer itself is deprecated and will be removed in a future version of PDFNet. It is strongly recommended to use the built-in rasterizer and to use the XPS print path where vector conversion is needed.

SetThinLineAdjustment(pixel_grid_fit, stroke_adjust)

Set thin line adjustment parameters.

Parameters:

• pixel_grid_fit (boolean) – if true (horizontal/vertical) thin lines will be snapped to integer pixel positions. This helps make thin lines look sharper and clearer. This option is turned off by default and it only works if path hinting is enabled.

• stroke_adjust (boolean) – if true auto stroke adjustment is enabled. Currently, this would make lines with sub-pixel width to be one-pixel wide. This option is turned on by default.

SetThinLineScaling(scaling)

This setting controls the thickness of zero-width lines when rendered. In a PDF, a line width of zero denotes the thinnest line that can be rendered at device resolution: 1 device pixel wide. However, on high-resolution devices, a single pixel can be nearly invisible.

Parameters:

scaling (double) – use this setting to increase the apparent thickness of these zero-width lines. 1.0 (1 pixel wide)

UpdateBuffer()

This function is typically called for progressive rendering, in which we don’t want to stop the main rendering thread. Since the rendering thread may modify separation channels, we don’t consider separations in progressive rendering.

e_BuiltIn = 0

high-quality, platform independent rasterizer.

e_GDIPlus = 1

GDI+ based rasterizer. (Deprecated)

e_op_off = 0

e_op_on = 1

e_op_pdfx_on = 2

e_postprocess_gradient_map = 2

e_postprocess_invert = 1

e_postprocess_night_mode = 3

e_postprocess_none = 0

property mp_rast

property thisown

The membership flag

class apryse_sdk.PDFTronCustomSecurityHandler(custom_id)

Bases: SecurityHandler

This class represents PDFTron Custom Security handler that applies PDFTron’s custom encryption method on save.

property thisown

The membership flag

class apryse_sdk.PDFView

Bases: object

PDFView is a utility class that can be used for interactive rendering of PDF documents.

In .NET environment PDFView is derived from System.Windows.Forms.Control and it can be used like a regular form (see PDFViewForm.cs in PDFView sample for C# for a concrete example).

PDFView implements some essential features such as double-buffering, multi-threaded rendering, scrolling, zooming, and page navigation that are essential in interactive rendering applications (e.g. in client PDF viewing and editing applications).

PDFView defines several coordinate spaces and it is important to understand their differences:

• Page Space refers to the space in which a PDF page is defined. It is determined by

a page itself and the origin is at the lower-left corner of the page. Note that Page Space is independent of how a page is viewed in PDFView and each page has its own Page space.

• Canvas Space refers to the tightest axis-aligned bounding box of all the pages given

the current page presentation mode in PDFView. For example, if the page presentation mode is e_single_continuous, all the pages are arranged vertically with one page in each row, and therefore the Canvas Space is rectangle with possibly large height value. For this reason, Canvas Space is also, like Page Space, independent of the zoom factor. Also note that since PDFView adds gaps between adjacent pages, the Canvas Space is larger than the space occupied by all the pages. The origin of the Canvas Space is located at the upper-left corner.

• Screen Space (or Client Space) is the space occupied by PDFView and its origin is at

the upper-left corner. Note that the virtual size of this space can extend beyond the visible region.

• Scrollable Space is the virtual space within which PDFView can scroll. It is determined

by the Canvas Space and the current zoom factor. Roughly speaking, the dimensions of the Scrollable Space is the dimensions of the Canvas Space timed by the zoom. Therefore, a large zoom factor will result in a larger Scrollable region given the same Canvas region. For this reason, Scrollable Space might also be referred to as Zoomed Canvas Space. Note that since PDFView adds gaps between pages in Canvas Space and these gaps are not scaled when rendered, the scrollable range is not exactly what the zoom factor times the Canvas range. For functions such as SetHScrollPos(), SetVScrollPos(), GetCanvasHeight(), and GetCanvasWidth(), it is the Scrollable Space that is involved.

Notes: PDFView is available on all platforms supported by PDFNet.

CanRedo()

CanUndo()

CancelAllThumbRequests()

CancelFindText()

Cancel the text search thread if FindText() is started in a different thread. Note that if the text search thread is currently being suspended by the render thread, it will only be canceled after it is awaken by the render thread.

CancelRendering()

Cancels rendering in progress. If PDFView is not busy rendering the page, the function has no side effects.

ClearSelection()

Remove any text selection.

ClearThumbCache()

Remove all thumbnails from the persistent disk cache.

CloseDoc()

Close the associated PDF document.

ConvCanvasPtToPagePt(pt, page_num=-1)

Converts a point expressed in canvas space to a point in a page space.

Parameters:

page_num (int) – the page number for the page used as the origin of the destination coordinate system. Negative values are used to represent the current page. Pages are indexed starting from one.

ConvCanvasPtToScreenPt(pt)

Converts a point expressed in canvas space to a point in screen space.

ConvPagePtToCanvasPt(pt, page_num=-1)

Converts a point from a page space to point in canvas space.

Parameters:

page_num (int) – the page number for the page used as the origin of the destination coordinate system. Negative values are used to represent the current page. Pages are indexed starting from one.

ConvPagePtToScreenPt(pt, page_num=-1)

Converts a point in a page space to a point in the screen space. If PDFView is in a non-continous page view mode, and the page is not visible, the result is undefined.

Parameters:

page_num (int) – the page number for the page used as the origin of the destination coordinate system. Negative values are used to represent the current page. Pages are indexed starting from one.

ConvScreenPtToCanvasPt(pt)

Converts a point expressed in screen space to a point in canvas space.

ConvScreenPtToPagePt(pt, page_num=-1)

Converts a point expressed in screen space to a point in a page space.

Parameters:

page_num (int) – the page number for the page used as the origin of the destination coordinate system. Negative values are used to represent the current page. Pages are indexed starting from one.

Destroy()

Frees the native memory of the object.

DocLock(cancel_threads)

Acquires a write lock on the currently open document, optionally canceling all threads accessing the document.

DocLockRead()

Locks the currently open document to prevent competing write threads (using Lock()) from accessing the document at the same time. Other reader threads however, will be allowed to access the document. Threads attempting to obtain write access to the document will wait in suspended state until the thread that owns the lock calls doc.UnlockRead(). Note: To avoid deadlocks obtaining a write lock while holding a read lock is not permitted and will throw an exception. If this situation is encountered please either unlock the read lock before the write lock is obtained or acquire a write lock (rather than read lock) in the first place.

DocTryLock(milliseconds=0)

Try acquiring a write lock on the currently open document, waiting no longer than specified number of milliseconds.

Return type:

boolean

Returns:

true if the document is locked for multi-threaded access, false otherwise.

DocTryLockRead(milliseconds=0)

Try acquiring a read lock on the current document, waiting no longer than specified number of milliseconds.

Return type:

boolean

Returns:

true if the document is locked for multi-threaded access, false otherwise.

DocUnlock()

Releases the write lock from the currently open document.

DocUnlockRead()

Releases the read lock from the currently open document.

EnableUndoRedo()

ExecuteAction(args)

FindTextAsync(search_str, match_case, match_whole_word, search_up, reg_exp)

Searches for the provided search string in the documents in a secondary thread, and calls FindTextHandler with the resulting selection.

Parameters:

• search_str (string) – The string to search for in the document

• match_case (boolean) – Set to true for case-sensitive search

• match_whole_word (boolean) – Set to true to match whole words only

• search_up (boolean) – Set to true to search up through the document

• reg_exp (boolean) – Set to true to interpret search_str as a regular expression

GetAnnotTypeUnder(x, y)

Return type:

int

Returns:

annotation type at the given point

Parameters:

• x (double) –

  • x coordinate of the input point

• y (double) –

  • y coordinate in the input point

GetAnnotationAt(x, y, distanceThreshold, minimumLineWeight)

Gets the annotation at the (x, y) position expressed in screen coordinates

Parameters:

• x (int) – x coordinate of the screen point

• y (int) – y coordinate of the screen point

• distanceThreshold (double) – Maximum distance from the point (x, y) to the annotation for the annot to be considered a hit.

• minimumLineWeight (double) – For very thin lines, it is almost impossible to hit the actual line. This specifies a minimum line thickness (in screen coordinates) for the purpose of calculating whether a point is inside the annotation or not.

Return type:

Annot

Returns:

the annotation at (x, y). If there is no annotation at (x, y), the returned annotation’s IsValid method will return false.

GetAnnotationListAt(x1, y1, x2, y2)

Returns a vector of annotations under the line (x1, y1, x2, y2) expressed in screen coordinates. Does not include form field annotations.

Parameters:

• x1 (int) – The x-coordinate of the first point of the line.

• y1 (int) – The y-coordinate of the first point of the line.

• x2 (int) – The x-coordinate of the second point of the line.

• y2 (int) – The y-coordinate of the second point of the line.

Return type:

std::vector< PDF::Annot,std::allocator< PDF::Annot > >

Returns:

A vector of annotations under the line (x1, y1, x2, y2) expressed in screen coordinates.

GetAnnotationsOnPage(page_num)

Returns a vector of all of the annotations on the given page.

Parameters:

page_num (int) – The page number for which to retrieve annotations.

Return type:

std::vector< PDF::Annot,std::allocator< PDF::Annot > >

Returns:

A vector of all of the annotations on the given page.

GetBuffer()

Returns the pointer to the internal memory buffer containing the rasterized image of the given page. The buffer size is at least ‘GetBufferHeightGetBufferStride’ bytes. The pixel data is stored in 8 bit per component, BGRA format.

GetBufferHeight()

Returns the width of the rendering buffer in pixels. Notes: this method is typically used only in PDFNet for C++

GetBufferStride()

Returns the stride of the rendering buffer in pixels. Notes: this method is typically used only in PDFNet for C++

GetBufferWidth()

Returns the width of the rendering buffer in pixels. Notes: this method is typically used only in PDFNet for C++

GetCanvasHeight()

Returns the height of the scrollable space.

GetCanvasWidth()

Returns the width of the scrollable space.

GetColorPostProcessMode()

Return type:

int

Returns:

the current color post processing mode.

GetCurrentPage()

Return type:

int

Returns:

the current page displayed in the view.

GetDeviceTransform(page_num=-1)

Return type:

Matrix2D

Returns:

the device transformation matrix. The device transformation matrix maps the page coordinate system to screen (or device) coordinate system.

Parameters:

page_num (int) – same as for PDFView.Conv???() methods.

Notes: to obtain a transformation matrix that maps screen coordinates to page coordinates, you can invert the device matrix. For example:

Common::Matrix2D scr2page(pdfview.GetDeviceTransform());
scr2page.Inverse();

GetDoc()

Return type:

PDFDoc

Returns:

Currently associated document with this PDFView.

GetExternalAnnotManager(args)

GetHScrollPos()

Return type:

double

Returns:

the current horizontal scroll position in the scrollable space.

GetLinkAt(x, y)

Gets the link info at a given point, specified in client space.

Parameters:

• x (int) – the x position in client space

• y (int) – the y position in client space

Return type:

LinkInfo

Returns:

the LinkInfo object with the link information or null if no link is found in the queried location.

Notes: To get valid links, SetUrlExtraction(boolean) must be set to true before opening the document.

GetNextRedoInfo()

GetNextUndoInfo()

GetOCGContext()

Return type:

Context

Returns:

the Optional Content Group (OCG) context associated with this PDFView, or NULL (i.e. context.IsValid()==false) if there is no OCG context associated with the view. If an OCG context associated with the view, optional content (such as PDF layers) will be selectively rendered based on the states of optional content groups in the given context.

GetPageCount()

Return type:

int

Returns:

the total number of pages in the document.

GetPageNumberFromScreenPt(x, y)

Return type:

int

Returns:

the number of the page located under the given screen coordinate. The positive number indicates a valid page, whereas number less than 1 means that no page was found.

GetPagePresentationMode()

Return type:

int

Returns:

the current page presentation mode.

GetPageRefViewMode()

Gets the reference page view mode. See more details about reference page view mode in {#setPageRefViewMode(int)}.

GetPageViewMode()

Return type:

int

Returns:

the current page viewing mode

GetPostProcessedColor(color)

Converts a color based on the view’s color post processing transformation.

Parameters:

color (ColorPt) – the color to be converted

Return type:

ColorPt

Returns:

the post-processed color

GetRotation()

Return type:

int

Returns:

The current rotation of this PDFView.

GetScreenRectForAnnot(annot, page_num=-1)

Gets the annotation bounding box in screen points

Parameters:

• annot (Annot) – target annotation

• page_num (int) – the page number that the annotation is on S

Return type:

Rect

Returns:

the annotation bounding box in screen points

GetSelection(pagenum=-1)

Return type:

Selection

Returns:

Current text selection for a given page

GetSelectionBeginPage()

Return type:

int

Returns:

the first page number that has text selection on it. Useful when there are selections on multiple pages at the same time.

GetSelectionEndPage()

Return type:

int

Returns:

the last page number that has text selection on it. Useful when there are selections on multiple pages at the same time.

GetTextSelectionMode()

Return type:

int

Returns:

the current selection mode used for text highlighting.

GetThumbAsync(page_num, instance)

Retrieves the specified thumbnail from the persistent thumbnail cache on disk, then calling proc on the resulting thumbnail.

Parameters:

• page_num (int) – The page number of the thumbnail.

• proc – A callback function that will be called after the thumbnail is retrieved, or if that retrieval fails.

• data – Custom data to be passed as a parameter to ‘proc’.

GetThumbInCache(page_num, buf, out_width, out_height)

Retrieves the specified thumbnail from the persistent thumbnail cache on disk if it is available.

Parameters:

• page_num (int) – The page number of the thumbnail.

• buf (UChar) – the buffer in which to store thumbnail data. This buffer should have space for GetThumbInCacheSize bytes.

• out_width (int) – the width of the thumbnail

• out_height (int) – the height of the thumbnail

Return type:

boolean

Returns:

true if the thumbnail is found in the cache and false otherwise.

GetThumbInCacheSize(page_num)

Gets the data size of a cached thumbnail.

Parameters:

page_num (int) – The page number of the thumbnail.

Return type:

int

Returns:

if the thumbnail is available returns the size of the thumbnail in bytes otherwise returns 0

GetVScrollPos()

Return type:

double

Returns:

the current vertical scroll position in the scrollable space.

GetVisiblePages()

Get a vector with the pages currently visible on the screen.

Return type:

std::vector< int,std::allocator< int > >

Returns:

a vector of the pages currently visible on the screen.

GetZoom()

Returns the current zoom factor.

Return type:

double

Returns:

current zoom (or scaling) component used to display the page content.

GotoFirstPage()

Sets the current page to the first page in the document.

Return type:

boolean

Returns:

true if successful, false otherwise.

GotoLastPage()

Sets the current page to the last page in the document.

Return type:

boolean

Returns:

true if successful, false otherwise.

GotoNextPage()

Sets the current page to the next page in the document.

Return type:

boolean

Returns:

true if successful, false otherwise.

GotoPreviousPage()

Sets the current page to the previous page in the document.

Return type:

boolean

Returns:

true if successful, false otherwise.

HasSelection()

Return type:

boolean

Returns:

return true if there is selection, false otherwise.

HasSelectionOnPage(ipage)

Return type:

boolean

Returns:

returns true if given page number has any text selection on it. Useful when there are selections on multiple pages at the same time.

HideAnnotation(annot)

Disable rendering of a particular annotation. This does not change the annotation itself, just how it is displayed in this viewer instance.

Parameters:

annot (Annot) – The annotation object to cease drawing for.

IsFinishedRendering(visible_region_only)

Parameters:

visible_region_only (boolean) –

• Specifies if the method refers only to currently

visible content.

Return type:

boolean

Returns:

true is the rendering thread finished rendering the view, false if the rendering is still in progress.

IsThereTextInRect(x1, y1, x2, y2)

Return type:

boolean

Returns:

true if there is a text in the given rectangle, false otherwise and point (x2, y2) is the end selection point. The points are defined in screen space.

OnScroll(pix_dx, pix_dy)

Scrolls the contents of the rendering buffer ‘pix_dx’ horizontally and ‘pix_dy’ vertically.

Parameters:

• pix_dx (int) – horizontal scroll offset, in pixels

• pix_dy (int) – vertical scroll offset, in pixels

OnSize(width, height)

Resize rendering buffer to new dimensions.

Parameters:

• width (int) –

  • The width of the target image in pixels.

• height (int) –

  • The height of the target image in pixels (the number of rows).

Notes: this method is typically used only in PDFNet for C++

OpenUniversalDoc(conversion)

Associates this PDFView with a given document conversion. The conversion will be performed page-by-page, asynchronously. The pdview object will be updated to display the conversion result

Parameters:

doc –

• A document to be displayed in the view.

PVM_SIZE = 4

PrepareAnnotsForMouse(page_num, distance_threshold, minimum_line_weight)

Requests for preparing annotations of the given page. Note: Annotations are going to be prepared asynchronously

Parameters:

• page_num (int) –

  • page number

• distance_threshold (double) –

  • Maximum distance from the point (x, y) to the annotation for the annot to be considered a hit.

• minimum_line_weight (double) –

  • For very thin lines, it is almost impossible to hit the actual line.

  This specifies a minimum line thickness (in screen coordinates) for the purpose of calculating whether a point is inside the annotation or not

PrepareWords(page_num)

Requests for preparing words of the given page. Note: Words are going to be prepared asynchronously

Parameters:

page_num (int) –

• page number

Redo()

RefreshAndUpdate(view_change)

Helper function that will refresh annotation and/or field appearances if needed, and then render modified page areas, all based on the contents of the view_change parameter.

Parameters:

view_change (ViewChangeCollection) – contains all the updated fields and rectangles.

RevertAllChanges()

RotateClockwise()

Rotates all pages in the document 90 degrees clockwise.

RotateCounterClockwise()

Rotates all pages in the document 90 degrees counter-clockwise.

Select(args)

Overload 1:

Selects text within the given region using the current text selection mode.

Return type:

boolean

Returns:

true if some text was selected, false otherwise.

:param x1:, y1, x2, y2 - two points (screen coordinates, origin located at the upper-left corner of this view)

defining the opposite corners of a selection rectangle.

Overload 2:

Selects texts using structural mode.

Return type:

boolean

Returns:

true if some texts were selected, false otherwise.

:param (x1:, y1), page1 - the first selection point (in page coordinates space) on page page1 :param (x2:, y2), page2 - the second selection point (in page coordinates space) on page page2

Overload 3:

Selects texts identified by Highlights.

Return type:

boolean

Returns:

true if some texts were selected, false otherwise.

Parameters:

highlights (Highlights) –

• an instance of Highlights class.

Overload 4:

Selects a region according to a Selection object

Return type:

boolean

Returns:

true if some texts were selected, false otherwise.

Parameters:

select (Selection) –

• an instance of the Selection class

SelectAll()

Selects all text on the page.

SelectWithSmartSnapping(args)

Overload 1:

Selects text within the given region using the current text selection mode with smart snap-to-start and snap-to-end modes.

Return type:

boolean

Returns:

true if some text was selected, false otherwise.

:param x1:, y1, x2, y2 - two points (screen coordinates, origin located at the upper-left corner of this view)

defining the opposite corners of a selection rectangle.

Overload 2:

Selects texts using structural mode with smart snap-to-start and snap-to-end modes.

Return type:

boolean

Returns:

true if some texts were selected, false otherwise.

:param (x1:, y1), page1 - the first selection point (in page coordinates space) on page page1 :param (x2:, y2), page2 - the second selection point (in page coordinates space) on page page2

SelectWithSnapping(args)

Overload 1:

Selects text within the given region using the current text selection mode with defined snap-to-start and snap-to-end modes.

Return type:

boolean

Returns:

true if some text was selected, false otherwise.

:param x1:, y1, x2, y2 - two points (screen coordinates, origin located at the upper-left corner of this view)

defining the opposite corners of a selection rectangle.

Parameters:

snap-to-end (snap_to_start:,) – if selected text should contain the whole word at start/end of selection points.

Overload 2:

Selects texts using structural mode with defined snap-to-start and snap-to-end modes.

Return type:

boolean

Returns:

true if some texts were selected, false otherwise.

:param (x1:, y1), page1 - the first selection point (in page coordinates space) on page page1 :param (x2:, y2), page2 - the second selection point (in page coordinates space) on page page2

Parameters:

snap-to-end (snap_to_start:,) – if selected text should contain the whole word at start/end of selection points

SetAntiAliasing(enable_aa)

Enable or disable anti-aliasing.

Anti-Aliasing is a technique used to improve the visual quality of images when displaying them on low resolution devices (for example, low DPI computer monitors).

Anti-aliasing is enabled by default.

SetBackgroundColor(r, g, b, a=255)

Sets the default background color used to paint the area surrounding each page.

:param r:, g, b - RGB color specifying the default background color.

Parameters:

a (int) –

• The alpha value of the background color. Default value is 255.

SetCaching(enabled)

Enables of disables caching of images, fonts, and other resources. Disabling caching can lower memory requirements at the expense of rendering speed.

Parameters:

enabled (boolean) – if true caching is enabled, if false caching is disabled. by default caching is enabled

SetColorPostProcessColors(white_color, black_color)

Sets the color post processing transformation. This transform is applied to the rasterized bitmap as the final step in the rasterization process, and is applied directly to the resulting bitmap (disregarding any color space information). Color post processing only supported for RGBA output. This mode will map the brightness of the original rasterized bitmap to a gradient between whiteColor and blackColor

Parameters:

• white_color (int) – The white color (ARGB) of the page.

• black_color (int) – The black color (ARGB) of the page.

SetColorPostProcessMapFile(image_file_contents)

Sets the color post processing transformation. This transform is applied to the rasterized bitmap as the final step in the rasterization process, and is applied directly to the resulting bitmap (disregarding any color space information). Color post processing only supported for RGBA output.

This mode will map the brightness of the original rasterized bitmap to a gradient in image_file_contents from left to right.

Parameters:

image_file_contents (Filter) – A filter with image file contents.

SetColorPostProcessMode(mode)

Set the color post processing transformation. This transform is applied to the rasterized bitmap as the final step in the rasterization process, and is applied directly to the resulting bitmap (disregarding any color space information). Color post processing only supported for RGBA output.

Parameters:

mode (int) – is the specific transform to be applied

SetCurrentPage(page_num)

Sets the current page to the given page.

Return type:

boolean

Returns:

true if successful, false otherwise.

SetCurrentPageProc(instance)

Sets the callback function (i.e. a delegate) that is called whenever current page number changes. This can be used to update the current page number within GUI applications etc.

Parameters:

• curr_pagenum_proc – Callback function (or a delegate in .NET).

• data – Custom data to be passed as a second parameter to ‘curr_pagenum_proc’.

SetCurrentZoomProc(instance)

Sets the callback function (i.e. a delegate) that is called whenever current zoom (magnification) changes. This can be used to update the current zoom number within GUI applications etc.

Parameters:

• curr_zoom_proc – Callback function (or a delegate in .NET).

• data – Custom data to be passed as a second parameter to ‘curr_zoom_proc’.

SetDefaultPageColor(r, g, b)

Sets the default ‘paper’ color used to draw background of each page.

:param r:, g, b - RGB color specifying the default page color.

SetDevicePixelDensity(dpi, scale_factor)

Set device pixel density

SetDoc(doc)

Associates this PDFView with a given PDF document.

Parameters:

doc (PDFDoc) –

• A document to be displayed in the view.

SetDrawAnnotations(render_annots)

Enable or disable annotation and forms rendering. By default, all annotations and form fields are rendered.

Parameters:

render_annots (boolean) – True to draw annotations, false otherwise.

SetErrorReportProc(instance)

Sets the error handling function to be called in case an error is encountered during page rendering.

Parameters:

• error_proc – Error handling callback function (or delegate in .NET)

• data – Custom data to be passed as a second parameter to ‘error_proc’.

SetFieldHighlightColor(new_field_highlight_color)

Set the highlight color for required fields

This option only has an effect if field highlighting is turned on using SetHighlightFields(true). Note that signature fields have their own highlight color, independent of this one (see setSignatureHighlightColor).

Parameters:

new_field_highlight_color (ColorPt) – the new highlight color, in rgba form.

SetFindTextHandler(instance)

Sets the FindText handling function to be called once FindTextAsync is done, whether it was interrupted, canceled, or completed.

Parameters:

instance (Callback) – A pointer to the Callback object

SetGamma(exp)

Sets the gamma factor used for anti-aliased rendering.

Parameters:

exp (double) – is the exponent value of gamma function. Typical values are in the range from 0.1 to 3.

Gamma correction can be used to improve the quality of anti-aliased image output and can (to some extent) decrease the appearance common anti-aliasing artifacts (such as pixel width lines between polygons).

Notes: Gamma correction is used only in the built-in rasterizer.

SetHScrollPos(pos)

Sets the horizontal scroll position in scrollable space.

Parameters:

the – new horizontal scroll position. The position should be in the range between 0 and GetCanvasWidth().

SetHighlightFields(highlight_fields)

Enable or disable highlighting form fields. Default is disabled.

Parameters:

highlight_fields (boolean) – true to highlight, false otherwise.

SetHorizontalAlign(align)

Sets the horizontal alignment used for rendering pages within the view.

Parameters:

align (int) –

an integer specifying the horizontal alignment. Depending of whether align is positive, negative, or zero - pages will be right, left or center aligned:

align<0 -> pages are left aligned. align==0 -> pages are centered. align>0 -> pages are right aligned.

SetImageSmoothing(smoothing_enabled=True)

Enable or disable image smoothing.

The rasterizer allows a trade-off between rendering quality and rendering speed. This function can be used to indicate the preference between rendering speed and quality.

Notes: image smoothing option has effect only if the source image has higher resolution that the output resolution of the image on the rasterized page. PDFNet automatically controls at what resolution/zoom factor, ‘image smoothing’ needs to take effect.

Parameters:

smoothing_enabled (boolean) – True to enable image smoothing, false otherwise. image smoothing is enabled.

SetJavaScriptEventCallBack(instance)

Sets the callback function (i.e. a delegate) for JavaScript action. Can be used to handle alert event which pops up a window with alert message.

Parameters:

• js_proc – Callback function (or a delegate in .NET).

• data – user defined data

SetOCGContext(ctx)

Sets the Optional Content Group (OCG) context that should be used when viewing the document. This function can be used to change the current OCG context. Optional content (such as PDF layers) will be selectively rendered based on the states of optional content groups in the given context.

Parameters:

ctx (Context) – Optional Content Group (OCG) context, or NULL if the rasterizer should render all content on the page.

Notes: Unlike PDFDraw.SetOCGContext() this method copies the given context. As a result, in order to modify the state of OCG groups in the current context use GetOCGContext() to obtain the currently selected content and then modify states.

SetOverprint(op)

Enable or disable support for overprint and overprint simulation. Overprint is a device dependent feature and the results will vary depending on the output color space and supported colorants (i.e. CMYK, CMYK+spot, RGB, etc).

By default overprint is only enabled for PDF/X files.

Parameters:

op (int) – e_op_on: always enabled; e_op_off: always disabled; e_op_pdfx_on: enabled for PDF/X files only.

SetPageBorderVisibility(border_visible)

Enables or disables drawing of a thin border around each page.

Parameters:

border_visible (boolean) –

• if true, the border will be visible.

SetPagePresentationMode(mode)

Sets the current page presentation mode.

Parameters:

mode (int) –

• the new page presentation mode.

The default PagePresentationMode is e_single_continuous.

SetPageRefViewMode(mode)

Sets the reference page view mode. In a non-continous page presentation mode, the reference page view mode is used to determine the page view mode upon a page change event. For example, if the reference page view mode is set to e_fit_width, the new page coming in will be displayed with width-fit mode.

Parameters:

mode (int) – The reference page view mode to set. Valid values are e_fit_page, e_fit_width, and e_fit_height.

SetPageSpacing(horiz_col_space, vert_col_space, horiz_pad, vert_pad)

Sets the vertical and horizontal padding and column spacing between adjacent pages in the view.

Parameters:

• horiz_col_space (int) – horizontal column spacing (represented in pixels) between adjacent pages in the view. Default is 10.

• vert_col_space (int) – vertical column spacing (represented in pixels) between adjacent pages in the view. Default is 10.

• horiz_pad (int) – horizontal padding (represented in pixels) on the left and right side of the view. Default is 10.

• vert_pad (int) – vertical padding (represented in pixels) on the top and bottom side of the view. Default is 10.

SetPageTransparencyGrid(trans_grid_visible)

Enables or disables the transparency grid (check board pattern) to reflect page transparency.

Parameters:

trans_grid_visible (boolean) –

• if true, the grid is turned on.

SetPageViewMode(mode)

Sets the page viewing mode

Parameters:

mode (int) –

• the new page viewing mode.

The default PageView mode is e_fit_width.

SetPathHinting(enable_hinting)

Enable or disable path hinting.

Parameters:

enable_hinting (boolean) – if true path hinting is enabled. Path hinting is used to slightly adjust paths in order to avoid or alleviate artifacts of hair line cracks between certain graphical elements. This option is turned on by default.

SetRasterizerType(type)

Sets the core graphics library used for rasterization and rendering. Using this method it is possible to quickly switch between different implementations. By default, PDFNet uses a built-in, high-quality, and platform independent rasterizer.

Parameters:

type (int) – Rasterizer type.

SetRenderBeginProc(instance)

Set a callback function that can be used to notify the client that PDFView is about to start rendering and modifying the contents of the rendering buffer.

Parameters:

• proc – A callback function that will be called just before PDFView starts rendering.

• data – Custom data to be passed as a parameter to ‘proc’.

Notes: this method is available only in the C++ SDK and not available in pre-packaged PDF viewing controls (.NET/Java/ActiveX).

SetRenderFinishProc(instance)

Set a callback function that can be used to notify the client that PDFView finished rendering and modifying the contents of the rendering buffer.

Parameters:

• proc – A callback function that will be called after PDFView is done with rendering.

• data – Custom data to be passed as a parameter to ‘proc’.

Notes: this method is available only in the C++ SDK and is not available in pre-packaged PDF viewing controls (.NET/Java/ActiveX).

SetRequestRenderInWorkerThreadProc(instance)

Sets a callback for issuing a render request on the UI thread. The callback will be called from a secondary thread. The called code is responsible for dispatching an event to the UI thread using the relevant mechanism. :param proc: The callback. :param data: Custom data to be passed as a parameter to ‘proc’.

SetRequiredFieldBorderColor(new_border_color)

Set the border color for required fields

This option only has an effect if field highlighting is turned on using SetHighlightFields(true).

Parameters:

new_border_color (ColorPt) – the new border color, in rgba form.

SetSignatureHighlightColor(new_signature_highlight_color)

Set the highlight color for signature fields

This option only has an effect if field highlighting is turned on using SetHighlightFields(true). Note that non-signature fields have their own highlight color, independent of this one (see setFieldHighlightColor)

Parameters:

new_signature_highlight_color (ColorPt) – the new signature highlight color, in rgba form.

SetSnappingMode(mode_flags)

Set the point snapping mode for the SnapToNearestInDoc method. By default SnapToNearestInDoc will snap to line endpoints, midpoints, and intersections.

Parameters:

mode_flag – a bitwise combination of the members of GeometryCollection::SnappingMode

SetTextSelectionMode(tm)

Sets the selection mode used for text highlighting.

Parameters:

tm (int) – the text selection mode.

SetThinLineAdjustment(pixel_grid_fit, stroke_adjust)

Set thin line adjustment parameters.

Parameters:

• pixel_grid_fit (boolean) – if true (horizontal/vertical) thin lines will be snapped to integer pixel positions. This helps make thin lines look sharper and clearer. This option is turned off by default and it only works if path hinting is enabled.

• stroke_adjust (boolean) – if true auto stroke adjustment is enabled. Currently, this would make lines with sub-pixel width to be one-pixel wide. This option is turned on by default.

SetUrlExtraction(enabled)

Enables or disables URL extraction.

Parameters:

enabled (boolean) – if true URL extraction is enabled, if false URL extraction is disabled.

by default URL extraction is disabled

Notes: If set to enabled when the document is already opened, it may not find links on pages that were already rendered. It is suggested to set this flag before opening the document.

SetVScrollPos(pos)

Sets the vertical scroll position in scrollable space.

Parameters:

the – new vertical scroll position. The position should be in the range between 0 and GetCanvasheight().

Should you want to center to a location (px, py) expressed in a page space, you can use the following code:

//focus view.SetCurrentPage(page_num); view.ConvPagePtToScreenPt(px, py, page_num); view.SetZoom((int)px, (int)py, view.GetZoom());

//center int width = view.GetBufferWidth(); int height = view.GetBufferHeight(); int dx = (int)(px - (double)width/2 + 0.5); int dy = (int)(py - (double)height/2 + 0.5); view.OnScroll(dx, dy);

SetVerticalAlign(align)

Sets the vertical alignment used for rendering pages within the view.

Parameters:

align (int) –

an integer specifying the vertical alignment. Depending of whether align is positive, negative, or zero - pages will be bottom, top or center aligned:

align<0 -> pages are top aligned. align==0 -> pages are centered. align>0 -> pages are bottom aligned.

static SetViewerCache(document, max_cache_size, on_disk)

Sets the cache parameters of the page cache on disk (which caches content streams and mipmapped images) for this specific document. These parameters will override the default cache

parameters. Note that if this function is called after the document has been rasterized, it has no effect.

type document:

SDFDoc

param document:

• The document whose settings will be modified.

type max_cache_size:

int

Parameters:

• max_cache_size –

  • The maximum size, in bytes, of the entire document’s page cache. Set to zero to disable the viewer cache.

  type on_disk:

  boolean

• on_disk –

  • If set to ‘true’, cache will be stored on the local filesystem. If set to ‘false’, cache will be stored in heap memory.

  Desktop: max_cache_size = 512 MB, on_disk = true | Mobile: max_cache_size = 100 MB, on_disk = false

SetZoom(args)

Overload 1:

Sets the zoom factor to a new value. The function zooms to a point at the center of the rendering buffer.

Parameters:

zoom (double) –

• new scaling component used to display the page content.

Return type:

boolean

Returns:

true if successful, false otherwise.

Overload 2:

Sets the zoom factor to a new value using the given pixel coordinate (x,y) as a zoom center, which will stay fixed on the screen.

The zoom point (x,y) is represented in the screen space, which starts in the upper-left corner of the client window.

Should you want to move (x, y) to the center of the client window, you can use the OnScroll() subsequently:

int x, y; double zoom; … view.SetZoom(x, y, zoom); int width = view.GetBufferWidth(); int height = view.GetBufferHeight(); int dx = (int)(x - (double)width/2 + 0.5); int dy = (int)(y - (double)height/2 + 0.5); view.OnScroll(dx, dy);

Parameters:

• x (int) –

  • the horizontal coordinate to zoom in.

• y (int) –

  • the vertical coordinate to zoom in.

• zoom (double) –

  • new scaling component used to display the page content.

Return type:

boolean

Returns:

true if successful, false otherwise.

SetupThumbnails(use_embedded, generate_at_runtime, use_disk_cache, thumb_max_side_length, max_abs_cache_size, max_perc_cache_size)

Specify the different thumbnail settings for the viewer. It is recommended that this not be called after SetDoc in order to avoid clearing cached thumbnails. Calling this method with different parameters will also clear the persistent disk cache if it is in use.

Parameters:

• use_embedded (boolean) – Enables or disables using thumbnails embedded in the PDF document as a preview of the rendered page. (Currently ignored - future versions may take advantage of embedded thumbnails)

• generate_at_runtime (boolean) – Enables or disables generating thumbnails at runtime.

• use_disk_cache (boolean) – Enables or disables caching thumbnails on disk. If possible thumbnails are cached in a persistent manner.

• thumb_max_side_length (int) – The maximum size, in pixels, of a dimension of generated thumbnails.

• max_abs_cache_size (int) – The absolute maximum size on disk, in bytes, for the temporary thumbnail cache.

• max_perc_cache_size (double) – The maximum percentage of free disk space, in the range 0 - 1.0, that the cache can take up.

ShowAnnotation(annot)

Enable rendering of a particular annotation. Only has an effect if HideAnnotation() has previously been called on the same annot.

Parameters:

annot (Annot) – The annotation object to resume rendering.

ShowRect(page_num, rect)

Changes the viewing area to fit a rectangle rect on page page_num. Rectangle must be specified in page coordinates. This will adjust current page and zoom appropriately.

Return type:

boolean

Returns:

true if successful, false otherwise.

SmartZoom(x, y)

Sets the zoom factor to a new value using the given pixel coordinate (x,y) to find an intersecting paragraph. The width of the paragraph helps to determine the zoom value, center of the paragraph is used as a zoom center. Paragraph has to contain more than one line and be wider than 1/5th of a page width. When called on a paragraph wider than current zoom level the new zoom level is set to fit the entire page(zoom out).

The zoom point (x,y) is represented in the screen space, which starts in the upper-left corner of the client window.

Parameters:

• x (int) –

  • the horizontal coordinate to look for a text block.

• y (int) –

  • the vertical coordinate to look for a text block.

Return type:

boolean

Returns:

true if successful, false if no paragraph intersects the given point.

SnapToNearestInDoc(screen_pt)

Snaps an xy coordinate pair (in screen space) to the nearest piece of document geometry.

TakeSnapshot(meta_info)

Undo()

Update(args)

Overload 1:

Redraws the contents of the buffer.

Overload 2:

Redraws the given area in the buffer.

Parameters:

update (Rect) – The rectangle to update expressed in screen coordinates.

Overload 3:

Redraws the area covered with a given annotation.

Parameters:

• annot (Annot) – The annotation to update.

• page_num (int) – The page number on which the annotation is located.

Overload 4:

Redraws all instances (Widgets) of the field.

Parameters:

field (Field) – the field for which to update all occurances

UpdateBuffer()

Update the internal memory buffer that can be returned by GetBuffer(). Since PDFView may not necessarily update the buffer until it finishes rendering the current viewing area, it is required to call UpdateBuffer() to force PDFView to write the current rasterized contents to the buffer. This is important for, say, calling GetBuffer() in a different thread to implement progressive rendering.

Notes: UpdateBuffer() ensures thread safety internally. In addition, PDFView calls UpdateBuffer() internally before the user-defined finishing-rendering callback function (specified by SetRenderFinishProc) is called, if applicable. this method is typically used only in PDFNet for C++.

UpdateOCGContext()

Prompts the PDFViewCtrl to update its list of optional content groups. Call this method if you modify the PDFDoc in a way that adds or removes a layer. For example, after using Stamper to create a stamp.

UpdatePageLayout()

Updates the page layout within the view. This function must be called after document page sequence is modified (such as when a page is being added to or removed from a document) or after changes to page dimensions (e.g. after a page is rotated or resized).

WereAnnotsForMousePrepared(page_num)

Return type:

boolean

Returns:

true if annotations of the given page have been prepared, false otherwise

Parameters:

page_num (int) –

• page number

WereWordsPrepared(page_num)

Return type:

boolean

Returns:

true if words of the given page has been prepared, false otherwise

Parameters:

page_num (int) –

• page number

e_facing = 3

e_facing_continuous = 4

e_facing_continuous_cover = 6

e_facing_cover = 5

e_fit_height = 2

e_fit_page = 0

e_fit_width = 1

e_rectangular = 1

e_single_continuous = 2

e_single_page = 1

e_structural = 0

e_structural_algorithm_2 = 2

e_zoom = 3

property thisown

The membership flag

apryse_sdk.PDFView_SetViewerCache(document, max_cache_size, on_disk)

Sets the cache parameters of the page cache on disk (which caches content streams and mipmapped images) for this specific document. These parameters will override the default cache

parameters. Note that if this function is called after the document has been rasterized, it has no effect.

type document:

SDFDoc

param document:

• The document whose settings will be modified.

type max_cache_size:

int

Parameters:

• max_cache_size –

  • The maximum size, in bytes, of the entire document’s page cache. Set to zero to disable the viewer cache.

  type on_disk:

  boolean

• on_disk –

  • If set to ‘true’, cache will be stored on the local filesystem. If set to ‘false’, cache will be stored in heap memory.

  Desktop: max_cache_size = 512 MB, on_disk = true | Mobile: max_cache_size = 100 MB, on_disk = false

class apryse_sdk.Page(args)

Bases: object

Page is a high-level class representing PDF page object (see ‘Page Objects’ in Section 3.6.2, ‘Page Tree,’ in PDF Reference Manual).

Among other associated objects, a page object contains:

• A series of objects representing the objects drawn on the page (See Element and ElementReader class for examples of how to extract page content).

• A list of resources used in drawing the page

• Annotations

• Beads, private metadata, optional thumbnail image, etc.

static AddRotations(r0, r1)

Rotate r0 clockwise by r1

Parameters:

• r0 (int) – first rotation.

• r1 (int) – second rotation.

Return type:

int

Returns:

returns r0 + r1

AnnotInsert(pos, annot)

Adds an annotation at the specified location in a page’s annotation array.

Parameters:

• pos (int) –

  • The location in the array to insert the object. The object is inserted

  before the specified location. The first element in an array has a pos of zero. If pos >= GetNumAnnots(), the method appends the annotation to the array.

• annot (Annot) –

  • The annotation to add.

AnnotPushBack(annot)

Adds an annotation to the end of a page’s annotation array.

Parameters:

annot (Annot) –

• The annotation to prepend in a page’s annotation array.

AnnotPushFront(annot)

Adds an annotation to the beginning of a page’s annotation array.

Parameters:

annot (Annot) –

• The annotation to append in a page’s annotation array.

AnnotRemove(args)

Overload 1:

Removes the given annotation from the page. Notes: Removing the annotation invalidates the given Annot object.

Parameters:

annot (Annot) – The annotation to remove.

Overload 2:

Removes the annotation at a given location. Notes: Removing the annotation invalidates any associated Annot object.

Parameters:

index (int) –

• A zero based index of the annotation to remove.

static DegreeToRotation(r)

Convert a number that represents rotation in degrees to a rotation enum.

Parameters:

r (int) – degree to convert to rotation. Valid numbers are multiples of 90.

Return type:

int

Returns:

one of four angles; e_0, e_90, e_180 or e_270. Returns e_0 if input is not a multiple 90.

FindInheritedAttribute(attrib)

Some of the page attributes are designated as inheritable. If such an attribute is omitted from a page object, its value is inherited from an ancestor node in the page tree. If the attribute is a required one, a value must be supplied in an ancestor node; if it is optional and no inherited value is specified, the default value should be used.

The function walks up the page inheritance tree in search for specified attribute.

Parameters:

attrib (string) – A string representing the attribute to search for.

Return type:

Obj

Returns:

if the attribute was found return a pointer to the value. Otherwise

the function return NULL.

Resources dictionary (Required; inheritable)

MediaBox rectangle (Required; inheritable) CropBox rectangle (Optional; inheritable) Rotate integer (Optional; inheritable)

FlattenField(field_to_flatten)

Flatten/Merge existing form field appearances with the page content and remove widget annotation.

Form ‘flattening’ refers to the operation that changes active form fields into a static area that is part of the PDF document, just like the other text and images in the document. A completely flattened PDF form does not have any widget annotations or interactive fields.

Parameters:

field_to_flatten (Field) – field to flatten

Notes: An alternative approach to set the field as read only is using Field.SetFlag(Field::e_read_only, true) method. Unlike Field.SetFlag(…), the result of FlattenField() operation can not be programatically reversed.

GetAnnot(index)

Returns the annotation on the page.

Return type:

Annot

Returns:

Annotation object. If the index is out of range returned Annot object is not valid (i.e. annot.IsValid() returns false).

Parameters:

index (int) –

• The index of the annotation to get on a page. The first annotation

on a page has an index of zero.

GetAnnots()

Returns SDF/Cos array containing annotation dictionaries. See Section 8.4 in the PDF Reference for a description of the annotation array.

Return type:

Obj

Returns:

an array of annotation dictionaries representing annotations associated with the page or NULL if page dictionary is not specified.

GetBox(type)

Return type:

Rect

Returns:

the box specified for the page object intersected with the media box.

Parameters:

type (int) – The type of the page bounding box. Possible values are: e_media, e_crop, e_bleed, e_trim, and e_art.

If the value for ‘type’ is e_crop, this call is equivalent to GetCropBox(). If the value for ‘type’ is e_media, this call is equivalent to GetMediaBox().

GetContents()

Return type:

Obj

Returns:

NULL if page is empty, otherwise a single stream or an array of streams.

GetCropBox()

Return type:

Rect

Returns:

the crop box for this page. The page dimensions are specified in user space coordinates.

The crop box is the region of the page to display and print. Notes: this method is equivalent to GetBox(Page::e_crop)

GetDefaultMatrix(args)

Return type:

Matrix2D

Returns:

the matrix that transforms user space coordinates to rotated and cropped coordinates. The origin of this space is the bottom-left of the rotated, cropped page.

Parameters:

• flip_y (boolean) – this parameter can be used to mirror the page. if ‘flip_y’ is true the Y axis is not flipped and it is increasing, otherwise Y axis is decreasing.

• box_type (int) – an optional parameter used to specify the page box/region that the matrix should map to. By default, the function transforms user space coordinates to cropped coordinates.

• angle (int) – an optional parameter used to specify page rotation in addition to the rotation specified in the page dictionary. This parameter is usually used to rotate the page without modifying the document itself.

GetIndex()

Return type:

int

Returns:

the Page number indication the position of this Page in document’s page sequence. Document’s page sequence is indexed from 1. Page number 0 means that the page is not part of document’s page sequence or that the page is not valid.

GetMediaBox()

Return type:

Rect

Returns:

the media box for this page. The page dimensions are specified in user space coordinates.

The media box defines the boundaries of the physical medium on which the page is to be printed. It may include any extended area surrounding the finished page for bleed, printing marks, or other such purposes.

Notes: this method is equivalent to GetBox(Page::e_media) :raises: if the page is missing media box the function throws Exception

GetNumAnnots()

Returns the number of annotations on a page. Widget annotations (form fields) are included in the count.

Return type:

int

Returns:

The number of annotations on a page.

GetPageHeight(args)

Return type:

double

Returns:

the height for the given page region/box taking into account page rotation attribute (i.e. /Rotate entry in page dictionary).

Parameters:

box_type (int) – indicates the page box/region to query for height.

GetPageWidth(args)

Return type:

double

Returns:

the width for the given page region/box taking into account page rotation attribute (i.e. /Rotate entry in page dictionary).

Parameters:

box_type (int) – indicates the page box/region to query for width.

GetResourceDict()

Return type:

Obj

Returns:

a pointer to the page resource dictionary.

Raises:

if the page is missing resource dictionary the function throws Exception

GetRotation()

Return type:

int

Returns:

the rotation value for this page.

GetSDFObj()

Returns the page dictionary.

Return type:

Obj

Returns:

the object to the underlying SDF/Cos object.

GetThumb()

Return type:

Obj

Returns:

Object representing the Image thumbnail.

GetTriggerAction(trigger)

Get the Action associated with the selected Page Trigger event.

Parameters:

trigger (int) – the type of trigger event to get

Return type:

Obj

Returns:

the Action Obj if present, otherwise NULL

GetUserUnitSize()

Returns the UserUnit value for the page. A UserUnit is a positive number giving the size of default user space units, in multiples of 1/72 inch.

Return type:

double

Returns:

the UserUnit value for the page. If the key is not present in the page dictionary the default of 1.0 is returned.

GetVisibleContentBox()

Return type:

Rect

Returns:

the bounding box for this page. The page dimensions are specified in user space coordinates.

The bounding box is defined as the smallest rectangle that includes all the visible content on the page.

HasTransition()

Tests whether this page has a transition.

IsValid()

Return type:

boolean

Returns:

true if this is a valid (non-null) page, false otherwise. If the function returns false the underlying SDF/Cos object is null or is not valid.

static RotationToDegree(r)

Convert a rotation to a number.

Parameters:

r (int) – rotation to convert to number

Return type:

int

Returns:

one of four numbers; 0, 90, 180 or 270.

Scale(scale)

A utility method used to scale physical dimensions of the page including all page content.

Parameters:

scale (double) –

A number greater than 0 which is used as a scale factor.

For example, calling page.Scale(0.5) will reduce physical dimensions of the page to half its original size, whereas page.Scale(2) will double the physical

dimensions of the page and will rescale all page content appropriately.

Notes: Unlike SetUserUnitSize(unit_size) which is only supported in PDF 1.6 (i.e. Acrobat 7) and above, page.Scale(sc) supports all PDF versions.

SetBox(type, box)

Sets the page bounding box specified by ‘page_region’ for this page.

Parameters:

• type (int) – The type of the page bounding box. Possible values are: e_media, e_crop, e_bleed, e_trim, and e_art.

• box (Rect) – A rectangle specifying the coordinates to set for the box. The coordinates are specified in user space units.

SetCropBox(box)

Sets the crop box for this page. The crop box is the region of the page to display and print.

Parameters:

box (Rect) – the new crop box for this page. The page dimensions are specified in user space coordinates.

The crop box defines the region to which the contents of the page are to be clipped (cropped) when displayed or printed.

Notes: this method is equivalent to SetBox(Page::e_crop)

SetMediaBox(box)

Sets the media box for this page.

Parameters:

box (Rect) – the new media box for this page. The page dimensions are specified in user space coordinates.

The media box defines the boundaries of the physical medium on which the page is to be printed. It may include any extended area surrounding the finished page for bleed, printing marks, or other such purposes.

Notes: this method is equivalent to SetBox(Page::e_media)

SetRotation(angle)

Sets the rotation value for this page.

Parameters:

angle (int) – Rotation value to be set for a given page. Must be one of the Page::Rotate values.

SetUserUnitSize(unit_size)

Sets the UserUnit value for a page.

Parameters:

unit_size (double) – A positive number giving the size of default user space units, in multiples of 1/72 inch.

Notes: This is a PDF 1.6 feature. See the implementation note 171 in PDF Reference for details.

static SubtractRotations(r0, r1)

Rotate r0 counter clockwise by r1.

Parameters:

• r0 (int) – first rotation.

• r1 (int) – second rotation.

Return type:

int

Returns:

returns r0 - r1

e_0 = 0

e_180 = 2

e_270 = 3

e_90 = 1

e_action_trigger_page_close = 12

e_action_trigger_page_open = 11

e_art = 4

e_bleed = 2

e_crop = 1

e_media = 0

e_trim = 3

e_user_crop = 5

property mp_page

property thisown

The membership flag

class apryse_sdk.PageIterator(args)

Bases: object

Supports a simple iteration over a generic collection.

Current()

Note: HasNext() must be true before calling Current()

Return type:

Page

Returns:

the current element in the collection

Destroy()

Frees the native memory of the object.

HasNext()

Return type:

boolean

Returns:

true if the iterator can be successfully advanced to the next element; false if the iterator is no longer valid.

Next()

Note: HasNext() must be true before calling Next() Advances the iterator to the next element of the collection.

property mp_impl

property thisown

The membership flag

class apryse_sdk.PageLabel(args)

Bases: object

PDF page labels can be used to describe a page. This is used to allow for non-sequential page numbering or the addition of arbitrary labels for a page (such as the inclusion of Roman numerals at the beginning of a book). PDFNet PageLabel object can be used to specify the numbering style to use (for example, upper- or lower-case Roman, decimal, and so forth), the starting number for the first page, and an arbitrary prefix to be pre-appended to each number (for example, “A-” to generate “A-1”, “A-2”, “A-3”, and so forth.)

PageLabel corresponds to the PDF Page Label object (Section 8.3.1, ‘Page Labels’ in the PDF Reference Manual.

Each page in a PDF document is identified by an integer page index that expresses the page’s relative position within the document. In addition, a document may optionally define page labels to identify each page visually on the screen or in print. Page labels and page indices need not coincide: the indices are fixed, running consecutively through the document starting from 1 for the first page, but the labels can be specified in any way that is appropriate for the particular document. For example, if the document begins with 12 pages of front matter numbered in roman numerals and the remainder of the document is numbered in Arabic, the first page would have a page index of 1 and a page label of i, the twelfth page would have index 12 and label xii, and the thirteenth page would have index 13 and label 1.

For purposes of page labeling, a document can be divided into labeling ranges, each of which is a series of consecutive pages using the same numbering system. Pages within a range are numbered sequentially in ascending order. A page’s label consists of a numeric portion based on its position within its labeling range, optionally preceded by a label prefix denoting the range itself. For example, the pages in an appendix might be labeled with decimal numeric portions prefixed with the string “A-” and the resulting page labels would be “A-1”, “A-2”,

Notes: There is no default numbering style; if no ‘S’ (Style) entry is present, page labels consist solely of a label prefix with no numeric portion. For example, if the ‘P’ entry (Prefix) specifies the label prefix “Appendix”, each page is simply labeled “Appendix” with no page number. If the ‘P’ entry is also missing or empty, the page label is an empty string.

Sample code (See PableLabelsTest sample project for examples):

// Create a page labeling scheme that starts with the first page in
// the document (page 1) and is using uppercase roman numbering
// style.
doc.SetPageLabel(1, PageLabel::Create(doc, PageLabel::e_roman_uppercase, "My Prefix ", 1));

// Create a page labeling scheme that starts with the fourth page in
// the document and is using decimal Arabic numbering style.
// Also the numeric portion of the first label should start with number
// 4 (otherwise the first label would be "My Prefix 1").
PageLabel L2 = PageLabel::Create(doc, PageLabel::e_decimal, "My Prefix ", 4);
doc.SetPageLabel(4, L2);

// Create a page labeling scheme that starts with the seventh page in
// the document and is using alphabetic numbering style. The numeric
// portion of the first label should start with number 1.
PageLabel L3 = PageLabel::Create(doc, PageLabel::e_alphabetic_uppercase, "My Prefix ", 1);
doc.SetPageLabel(7, L3);

// Read page labels from an existing PDF document.
PageLabel label;
for (int i=1; i=doc.GetPageCount(); ++i) {
label = doc.GetPageLabel(i);
if (label.IsValid()) {
  UString title = label.GetLabelTitle(i);
}

static Create(args)

Creates a new PageLabel.

Parameters:

• doc (SDFDoc) – A document to which the page label is added.

• style (int) – The numbering style for the label.

• prefix (string) – The string used to prefix the numeric portion of the page label.

• start_at (int) – the value to use when generating the numeric portion of the first label in this range; must be greater than or equal to 1.

Return type:

PageLabel

Returns:

newly created PageLabel object.

GetFirstPageNum()

Return type:

int

Returns:

the first page in the range associated with this label or -1 if the label is not associated with any page.

GetLabelTitle(page_num)

Return type:

string

Returns:

the full label title that is in effect for the given page. If there is no label object in effect, this method returns an empty string.

GetLastPageNum()

Return type:

int

Returns:

the last page in the range associated with this label or -1 if the label is not associated with any page.

GetPrefix()

Return type:

string

Returns:

the string used to prefix the numeric portion of the page label

GetSDFObj()

Return type:

Obj

Returns:

The pointer to the underlying SDF/Cos object.

GetStart()

Return type:

int

Returns:

the value to use when generating the numeric portion of the first label in this range; must be greater than or equal to 1.

GetStyle()

Return type:

int

Returns:

page numbering style.

IsValid()

Return type:

boolean

Returns:

whether this is a valid (non-null) PageLabel. If the function returns false the underlying SDF/Cos object is null or is not valid and the PageLabel object should be treated as null as well.

SetPrefix(prefix)

Parameters:

prefix (string) – the string used to prefix the numeric portion of the page label.

SetStart(start_at)

Parameters:

start_at (int) – the value to use when generating the numeric portion of the first label in this range; must be greater than or equal to 1.

SetStyle(style)

Sets the numbering style for the label.

Parameters:

style (int) – the numbering style for the label.

You may use label style to customize the page numbering schemes used throughout a document. There are three numbering formats:

• decimal (often used for normal page ranges)

• roman (often used for front matter such as a preface)

• alphabetic (often used for back matter such as appendices)

Notes: There is no default numbering style; if no ‘S’ (Style) entry is present, page labels consist solely of a label prefix with no numeric portion.

e_alphabetic_lowercase = 4

Lowercase letters (a to z for the first 26 pages, aa to zz for the next 26, and so on)

e_alphabetic_uppercase = 3

Uppercase letters (A to Z for the first 26 pages, AA to ZZ for the next 26, and so on)

e_decimal = 0

Decimal Arabic numerals

e_none = 5

No numeric portion in the label

e_roman_lowercase = 2

Lowercase Roman numerals

e_roman_uppercase = 1

Uppercase Roman numerals

property thisown

The membership flag

apryse_sdk.PageLabel_Create(args)

Creates a new PageLabel.

Parameters:

• doc (SDFDoc) – A document to which the page label is added.

• style (int) – The numbering style for the label.

• prefix (string) – The string used to prefix the numeric portion of the page label.

• start_at (int) – the value to use when generating the numeric portion of the first label in this range; must be greater than or equal to 1.

Return type:

PageLabel

Returns:

newly created PageLabel object.

class apryse_sdk.PageSet(args)

Bases: object

PageSet is a container of page numbers ordered following a linear sequence. The page numbers are integers and must be greater than zero. Duplicates are allowed.

(NOTE: This is not a mathematical set)

AddPage(one_page)

Add a value to the sequence.

Parameters:

one_page (int) – The page number being added

AddRange(args)

Add a range of values to the sequence. Reverse ordering is legal.

Parameters:

• range_start (int) – The starting value in the range

• range_end (int) – The ending value in the range

• filter (int) – -e_all: Default, includes all pages in the range -e_odd: Includes odd numbers in the range (discards even numbers) -e_even: Includes even numbers in the range (discards odd numbers)

Destroy()

Frees the native memory of the object.

e_all = 0

e_even = 1

e_odd = 2

property mp_impl

property thisown

The membership flag

apryse_sdk.Page_AddRotations(r0, r1)

Rotate r0 clockwise by r1

Parameters:

• r0 (int) – first rotation.

• r1 (int) – second rotation.

Return type:

int

Returns:

returns r0 + r1

apryse_sdk.Page_DegreeToRotation(r)

Convert a number that represents rotation in degrees to a rotation enum.

Parameters:

r (int) – degree to convert to rotation. Valid numbers are multiples of 90.

Return type:

int

Returns:

one of four angles; e_0, e_90, e_180 or e_270. Returns e_0 if input is not a multiple 90.

apryse_sdk.Page_RotationToDegree(r)

Convert a rotation to a number.

Parameters:

r (int) – rotation to convert to number

Return type:

int

Returns:

one of four numbers; 0, 90, 180 or 270.

apryse_sdk.Page_SubtractRotations(r0, r1)

Rotate r0 counter clockwise by r1.

Parameters:

• r0 (int) – first rotation.

• r1 (int) – second rotation.

Return type:

int

Returns:

returns r0 - r1

class apryse_sdk.Paragraph(args, kwargs)

Bases: ContentNode

A Paragraph is a content node that contains a list of TextRun objects.

AddTabStop(val)

Adds a tab stop to the paragraph style.

Parameters:

val (double) – The position of the tab stop to add.

AddText(text)

Add another text run to the paragraph

Parameters:

text (string) – The text to add

Return type:

TextRun

Returns:

The newly created TextRun object

Destroy()

GetBorderThickness()

Gets the border thickness for the paragraph style.

Return type:

double

Returns:

The border thickness for the paragraph style.

GetDefaultTabStop()

Gets the default tab stop position for the paragraph style.

Return type:

double

Returns:

The default tab stop position for the paragraph style.

GetEndIndent()

Gets the end indent for the paragraph style.

Return type:

double

Returns:

The end indent value for the paragraph style.

GetJustificationMode()

Get justification mode for the paragraph

Return type:

int

Returns:

Justification mode for paragraph style

GetNextTabStop(val)

Gets the next tab stop position for the paragraph style, given a starting position.

Parameters:

val (double) – The starting position.

Return type:

double

Returns:

The position of the next tab stop.

GetSpaceAfter()

Get the “space after” value for the paragraph style

Return type:

double

Returns:

“space after” value for paragraph style

GetSpaceBefore()

Get the “space before” value for the paragraph style

Return type:

double

Returns:

“space before” value for paragraph style

GetSpacesPerTab()

Gets the number of spaces per tab for the paragraph style.

Return type:

int

Returns:

The number of spaces per tab for the paragraph style.

GetStartIndent()

Gets the start indent for the paragraph style.

Return type:

double

Returns:

The start indent value for the paragraph style.

GetTextIndent()

Gets the text indent for the paragraph style.

Return type:

double

Returns:

The text indent value for the paragraph style.

IsDisplayRtl()

Checks if the paragraph style has the right-to-left (RTL) property set.

Return type:

boolean

Returns:

True if the display is RTL, false otherwise.

SetBorder(thickness, red, green, blue)

Sets the border for the paragraph style.

Parameters:

• thickness (double) – The border thickness.

• red (int) – The red component of the border color.

• green (int) – The green component of the border color.

• blue (int) – The blue component of the border color.

SetDefaultTabStop(val)

Sets the default tab stop position for the paragraph style.

Parameters:

val (double) – The default tab stop position to set.

SetDisplayRtl(val)

Sets the right-to-left (RTL) property for the paragraph style.

Parameters:

val (boolean) – The value to set. True if RTL, false if not.

SetEndIndent(val)

Sets the end indent for the paragraph style.

Parameters:

val (double) – The end indent value to set.

SetJustificationMode(val)

Set justification mode for paragraph style

Parameters:

val (int) – The justification mode to set

SetSpaceAfter(val)

Set the “space after” value for paragraph style

Parameters:

val (double) – The “space after” value to set

SetSpaceBefore(val)

Set the “space before” value for the paragraph style

Parameters:

val (double) – The “space before” value to set

SetSpacesPerTab(val)

Sets the number of spaces per tab for the paragraph style.

Parameters:

val (int) – The number of spaces per tab to set.

SetStartIndent(val)

Sets the start indent for the paragraph style.

Parameters:

val (double) – The start indent value to set.

SetTextIndent(val)

Sets the text indent for the paragraph style.

Parameters:

val (double) – The text indent value to set.

e_text_justification_invalid = 0

Text justification is invalid

e_text_justify_center = 3

Text is justified centered

e_text_justify_left = 1

Text is left justified

e_text_justify_right = 2

Text is right justified

property thisown

The membership flag

class apryse_sdk.PathData(args)

Bases: object

Contains the information required to draw the path. Contains an array of PathSegmentType Operators and corresponding path data Points. A point may be on or off (off points are control points). The meaning of a point depends on associated id (or segment type) in the path segment type array.

GetGlyphIndex()

Return type:

int

Returns:

The glyph index of the requested path. 0 stands for ‘.notdef’ glyph.

GetOperators()

Get the current operators.

Return type:

std::vector< unsigned char,std::allocator< unsigned char > >

Returns:

The existing PathSegmentType operators.

GetPoints()

Get the current data points.

Return type:

std::vector< double,std::allocator< double > >

Returns:

The existing data points.

IsDefined()

If PathData was acquired from Font::GetGlyphPath then is method will indicate if this is an ‘undefined character code’.

Return type:

boolean

Returns:

True if this is valid, otherwise false.

Notes: See Font::GetGlyphPath for more information regarding what an ‘undefined character code’ means.

SetOperators(operators)

Overwrite the existing operators.

Parameters:

operators (std::vector< unsigned char,std::allocator< unsigned char > >) –

• The new operators to use.

SetPoints(points)

Overwrite the existing data points.

Parameters:

points (std::vector< double,std::allocator< double > >) –

• The new data points to use.

e_closepath = 6

e_conicto = 4

e_cubicto = 3

e_lineto = 2

e_moveto = 1

e_rect = 5

property glyph_index

property is_def

property oprs

property pts

property thisown

The membership flag

class apryse_sdk.PatternColor(args)

Bases: object

Patterns are quite general, and have many uses; for example, they can be used to create various graphical textures, such as weaves, brick walls, sunbursts, and similar geometrical and chromatic effects.

Patterns are specified in a special family of color spaces named Pattern, whose ‘color values’ are PatternColor objects instead of the numeric component values used with other spaces. Therefore PatternColor is to pattern color space what is ColorPt to all other color spaces.

A tiling pattern consists of a small graphical figure called a pattern cell. Painting with the pattern replicates the cell at fixed horizontal and vertical intervals to fill an area. The effect is as if the figure were painted on the surface of a clear glass tile, identical copies of which were then laid down in an array covering the area and trimmed to its boundaries. This is called tiling the area.

The pattern cell can include graphical elements such as filled areas, text, and sampled images. Its shape need not be rectangular, and the spacing of tiles can differ from the dimensions of the cell itself.

The order in which individual tiles (instances of the cell) are painted is unspecified and unpredictable; it is inadvisable for the figures on adjacent tiles to overlap.

Destroy()

Frees the native memory of the object.

GetBBox()

Return type:

Rect

Returns:

A rectangle in the pattern coordinate system giving the coordinates of the left, bottom, right, and top edges, respectively, of the pattern cell’s bounding box. These boundaries are used to clip the pattern cell.

Notes: for patterns other than Tiling this method throws an exception.

GetMatrix()

Return type:

Matrix2D

Returns:

pattern matrix, a transformation matrix that maps the pattern’s internal coordinate system to the default coordinate system of the pattern’s parent content stream (the content stream in which the pattern is defined as a resource). The concatenation of the pattern matrix with that of the parent content stream establishes the pattern coordinate space, within which all graphics objects in the pattern are interpreted.

GetSDFObj()

Return type:

Obj

Returns:

the underlying SDF/Cos object

GetShading()

Return type:

Shading

Returns:

The shading object defining the shading pattern’s gradient fill.

Notes: for patterns other than Shading this method throws an exception.

GetTilingType()

Return type:

int

Returns:

the tiling type identifier that controls adjustments to the spacing of tiles relative to the device pixel grid:

Notes: for patterns other than Tiling this method throws an exception.

GetType()

Return type:

int

Returns:

The pattern type

GetXStep()

Return type:

double

Returns:

the desired horizontal spacing between pattern cells, measured in the pattern coordinate system.

Notes: that XStep and YStep may differ from the dimensions of the pattern cell implied by the BBox entry. This allows tiling with irregularly shaped figures. XStep and YStep may be either positive or negative, but not zero.

for patterns other than Tiling this method throws an exception.

GetYStep()

Return type:

double

Returns:

the desired vertical spacing between pattern cells, measured in the pattern coordinate system.

Notes: for patterns other than Tiling this method throws an exception.

e_colored_tiling_pattern = 1

e_constant_spacing = 0

e_constant_spacing_fast_fill = 2

e_no_distortion = 1

e_null = 3

e_shading = 2

e_uncolored_tiling_pattern = 0

property mp_pc

property thisown

The membership flag

class apryse_sdk.Point(args)

Bases: TRN_point

property thisown

The membership flag

class apryse_sdk.PolyLine(args)

Bases: LineAnnot

This header defines classes for the Polygon and PolyLine annotations. Polygon annotations (PDF 1.5) display closed polygons on the page. Such polygons may have any number of vertices connected by straight lines. Polyline annotations (PDF 1.5) are similar to polygons, except that the first and last vertex are not implicitly connected.

static Create(doc, pos)

Creates a new PolyLine annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the PolyLine annotation is added.

• pos (Rect) – A rectangle specifying the PolyLine annotation’s bounds in default user space units.

Return type:

PolyLine

Returns:

A newly created blank PolyLine annotation.

static CreateAnnot(doc, pos)

GetIntentName()

Returns the intent name as a value of the “IntentName” enumeration type.

Return type:

int

Returns:

The intent type of the annotation.

See also: IntentType

GetVertex(idx)

Returns the vertex(as a Point object) corresponding to the index within the Vertices array.

Parameters:

idx (int) – The index of the vertex, should be less than the value returned by GetVertexCount().

Return type:

Point

Returns:

A Point object corresponding to the vertex in the specified index position.

Notes: The Vertices are the points between which the lines are drawn. The viewer can draw either the straight lines or the smoothly connecting ones.

GetVertexCount()

Returns the number of vertices in the Vertices array.

Return type:

int

Returns:

the number of vertices.

Notes: The Vertices are the points between which the lines are drawn. The viewer can draw either the straight lines or the smoothly connecting ones.

SetIntentName(mode)

Sets the Intent name as a value of the “IntentName” enumeration type. (Optional; PDF 1.6 )

Parameters:

mode (int) – The intent name of the annotation.

See also: IntentType

SetVertex(idx, pt)

Sets the vertex(in Point object form) corresponding to the index within the Vertices array.

Parameters:

• idx (int) – The index of the vertex.

• pt (Point) – A Point object corresponding to the vertex to be added to the array.

Notes: The Vertices are the points between which the lines are drawn. The viewer can draw either the straight lines or the smoothly connecting ones.

e_PolyLineDimension = 1

The polyline annotation is intended to function as a dimension. (PDF 1.7)

e_PolygonCloud = 0

The annotation is intended to function as a cloud object.

e_PolygonDimension = 2

The polygon annotation is intended to function as a dimension. (PDF 1.7)

e_Unknown = 3

Non-standard intent type

property thisown

The membership flag

apryse_sdk.PolyLine_Create(doc, pos)

Creates a new PolyLine annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the PolyLine annotation is added.

• pos (Rect) – A rectangle specifying the PolyLine annotation’s bounds in default user space units.

Return type:

PolyLine

Returns:

A newly created blank PolyLine annotation.

apryse_sdk.PolyLine_CreateAnnot(doc, pos)

class apryse_sdk.Polygon(args)

Bases: PolyLine

static Create(doc, pos)

Creates a new Polygon annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the Polygon annotation is added.

• pos (Rect) – A rectangle specifying the Polygon annotation’s bounds in default user space units.

Return type:

Polygon

Returns:

A newly created blank Polygon annotation.

static CreateAnnot(doc, pos)

property thisown

The membership flag

apryse_sdk.Polygon_Create(doc, pos)

Creates a new Polygon annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the Polygon annotation is added.

• pos (Rect) – A rectangle specifying the Polygon annotation’s bounds in default user space units.

Return type:

Polygon

Returns:

A newly created blank Polygon annotation.

apryse_sdk.Polygon_CreateAnnot(doc, pos)

class apryse_sdk.Popup(args)

Bases: Annot

A pop-up annotation (PDF 1.3) displays text in a pop-up window for entry and editing. It shall not appear alone but is associated with a markup annotation, its parent annotation, and shall be used for editing the parent’s text. It shall have no appearance stream or associated actions of its own and shall be identified by the Popup entry in the parent’s annotation dictionary.

static Create(doc, pos)

Creates a new Popup annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the Popup annotation is added.

• pos (Rect) – A rectangle specifying the Popup annotation’s bounds in default user space units.

Return type:

Popup

Returns:

A newly created blank Popup annotation.

static CreateAnnot(doc, pos)

GetParent()

Returns the parent annotation of the Popup annotation.

Return type:

Annot

Returns:

An annot object which is the parent annotation of the Popup annotation.

Notes: This annotation object represents the parent annotation with which this pop-up annotation shall be associated. If this entry is present, the parent annotation’s Contents, M, C, and T entries shall override those of the pop-up annotation itself.

IsOpen()

Returns the initial opening condition of Popup.

Return type:

boolean

Returns:

A bool indicating whether the Popup is initially open.

Notes: This is a flag specifying whether the pop-up annotation’s window shall initially be displayed. Default value: false (closed).

SetOpen(is_open)

Sets the initial opening condition of Popup. (Optional)

Parameters:

is_open (boolean) – A bool indicating whether the Popup is initially open.

Notes: This is a flag specifying whether the pop-up annotation’s window shall initially be displayed. Default value: false (closed).

SetParent(parent)

Sets the Parent annotation of the Popup annotation. (Optional)

Parameters:

parent (Annot) – An annot object which is the parent annotation of the Popup annotation.

Notes: This annotation object represents the parent annotation with which this pop-up annotation shall be associated. If this entry is present, the parent annotation’s Contents, M, C, and T entries shall override those of the pop-up annotation itself.

property thisown

The membership flag

apryse_sdk.Popup_Create(doc, pos)

Creates a new Popup annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the Popup annotation is added.

• pos (Rect) – A rectangle specifying the Popup annotation’s bounds in default user space units.

Return type:

Popup

Returns:

A newly created blank Popup annotation.

apryse_sdk.Popup_CreateAnnot(doc, pos)

class apryse_sdk.PowerPointOutputOptions

Bases: object

A class containing options common to ToPowerPoint functions

SetCustomOCRLanguage(ocrlang)

Specifies the custom OCR languages to use. Notes: Use 3-letter ISO 639-2 language codes, separated by spaces. Example: “eng deu spa fra”. The default is English.

Parameters:

ocrlang (string) – the OCR language(s).

SetLanguage(language)

Specifies the OCR language. Default is automatic language detection.

Parameters:

language (int) – the OCR language.

SetPDFPassword(password)

Specifies the password if the PDF requires one.

Parameters:

password (string) – the PDF password, if required; an empty string otherwise.

SetPages(page_from, page_to)

Specifies a range of pages to be converted. By default all pages are converted. The first page has the page number of 1.

Parameters:

• page_from (int) – the first page to be converted.

• page_to (int) – the last page to be converted (inclusive). Use a negative value to specify the last page in the PDF.

SetPreferredOCREngine(engine)

Specifies preferred OCR engine.

Parameters:

engine (int) – The PreferredOCREngine to OCR.

property thisown

The membership flag

class apryse_sdk.Print

Bases: object

static StartPrintJob(args)

Overload 1:

(Windows Only) Print the PDFDoc to a printer. Depending on the OS and installed libraries, the PDFDoc will be sent using the GDI or the XPS print path. This function will block until the print job is done at the OS level.

Notes: If the printer is grayscale, only grayscale data will be sent.

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to be printed

• in_printerName (string) – the name of the printer to print to

• in_jobName (string) – the name of the job for print queue monitoring, can be empty.

• in_outputFileName (string) – if not empty, the name of the output file to save the printout into. This could be a PostScript, PCL, XPS or other file.

• in_pagesToPrint (PageSet) – a PageSet specifying which pages to print.

• in_printMode – options for the printer, see the PrinterMode class below.

• in_cancel (boolean) – set this to true to cancel the print job.

• in_context (Context) – (Optional) Optional Content Group setting, for example from PDFViewCtrl::GetOCGContext.

Return type:

void

Returns:

void. Throws a trn::Common::Exception on failure.

Overload 2:

(Windows Only) Print the PDFDoc to a printer. Depending on the OS and installed libraries, the PDFDoc will be sent using the GDI or the XPS print path. This function will block until the print job is done at the OS level.

Notes: Same functionality as other StartPrintJob but with char types for printer name, job name, output file name If the printer is grayscale, only grayscale data will be sent.

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to be printed

• in_printerName (string) – the name of the printer to print to

• in_jobName (string) – the name of the job for print queue monitoring, can be empty.

• in_outputFileName (string) – if not empty, the name of the output file to save the printout into. This could be a PostScript, PCL, XPS or other file.

• in_pagesToPrint (PageSet) – a PageSet specifying which pages to print.

• in_printMode – options for the printer, see the PrinterMode class below.

• in_cancel (boolean) – set this to true to cancel the print job.

• in_context (Context) – (Optional) Optional Content Group setting, for example from PDFViewCtrl::GetOCGContext.

Return type:

void

Returns:

void. Throws a trn::Common::Exception on failure.

Overload 3:

(Windows Only) Print the PDFDoc to a printer. Depending on the OS and installed libraries, the PDFDoc will be sent using the GDI or the XPS print path. This function will block until the print job is done at the OS level.

Notes: Same functionality as other StartPrintJob but with char types for printer name, job name, output file name If the printer is grayscale, only grayscale data will be sent.

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to be printed

• in_printerName (string) – the name of the printer to print to

• in_jobName (string) – the name of the job for print queue monitoring, can be empty.

• in_outputFileName (string) – if not empty, the name of the output file to save the printout into. This could be a PostScript, PCL, XPS or other file.

• in_pagesToPrint (PageSet) – a PageSet specifying which pages to print.

• in_printMode – options for the printer, see the PrinterMode class below.

• in_cancel (boolean) – set this to true to cancel the print job.

• in_context – (Optional) Optional Content Group setting, for example from PDFViewCtrl::GetOCGContext.

Return type:

void

Returns:

void. Throws a trn::Common::Exception on failure.

Overload 4:

(Windows Only) Print the PDFDoc to a printer. Depending on the OS and installed libraries, the PDFDoc will be sent using the GDI or the XPS print path. This function will block until the print job is done at the OS level.

Notes: Same functionality as other StartPrintJob but with char types for printer name, job name, output file name If the printer is grayscale, only grayscale data will be sent.

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to be printed

• in_printerName (string) – the name of the printer to print to

• in_jobName (string) – the name of the job for print queue monitoring, can be empty.

• in_outputFileName (string) – if not empty, the name of the output file to save the printout into. This could be a PostScript, PCL, XPS or other file.

• in_pagesToPrint (PageSet) – a PageSet specifying which pages to print.

• in_printMode – options for the printer, see the PrinterMode class below.

• in_cancel – set this to true to cancel the print job.

• in_context – (Optional) Optional Content Group setting, for example from PDFViewCtrl::GetOCGContext.

Return type:

void

Returns:

void. Throws a trn::Common::Exception on failure.

Overload 5:

(Windows Only) Print the PDFDoc to a printer. Depending on the OS and installed libraries, the PDFDoc will be sent using the GDI or the XPS print path. This function will block until the print job is done at the OS level.

Notes: Same functionality as other StartPrintJob but with char types for printer name, job name, output file name If the printer is grayscale, only grayscale data will be sent.

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to be printed

• in_printerName (string) – the name of the printer to print to

• in_jobName (string) – the name of the job for print queue monitoring, can be empty.

• in_outputFileName (string) – if not empty, the name of the output file to save the printout into. This could be a PostScript, PCL, XPS or other file.

• in_pagesToPrint (PageSet) – a PageSet specifying which pages to print.

• in_printMode – options for the printer, see the PrinterMode class below.

• in_cancel – set this to true to cancel the print job.

• in_context – (Optional) Optional Content Group setting, for example from PDFViewCtrl::GetOCGContext.

Return type:

void

Returns:

void. Throws a trn::Common::Exception on failure.

Overload 6:

(Windows Only) Print the PDFDoc to a printer. Depending on the OS and installed libraries, the PDFDoc will be sent using the GDI or the XPS print path. This function will block until the print job is done at the OS level.

Notes: Same functionality as other StartPrintJob but with char types for printer name, job name, output file name If the printer is grayscale, only grayscale data will be sent.

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to be printed

• in_printerName (string) – the name of the printer to print to

• in_jobName (string) – the name of the job for print queue monitoring, can be empty.

• in_outputFileName (string) – if not empty, the name of the output file to save the printout into. This could be a PostScript, PCL, XPS or other file.

• in_pagesToPrint – a PageSet specifying which pages to print.

• in_printMode – options for the printer, see the PrinterMode class below.

• in_cancel – set this to true to cancel the print job.

• in_context – (Optional) Optional Content Group setting, for example from PDFViewCtrl::GetOCGContext.

Return type:

void

Returns:

void. Throws a trn::Common::Exception on failure.

property thisown

The membership flag

class apryse_sdk.PrintToPdfModule

Bases: object

The class PrintToPdfModule. An interface into Apryse SDKs Print To PDF functionality

static IsModuleAvailable()

Find out whether the PrintToPdf module is available.

Return type:

boolean

Returns:

returns true if PrintToPdf can be performed.

static PrintToPdf(pdf_doc, file_to_print, options=None)

Generate a PDF file by printing a document to the Apryse PDF printer via the Windows print verb.

Parameters:

• pdf_doc (PDFDoc) – – The destination document.

• file_to_print (string) – – The source document filename.

• options (PrintToPdfOptions) – – Print options (optional).

property thisown

The membership flag

apryse_sdk.PrintToPdfModule_IsModuleAvailable()

Find out whether the PrintToPdf module is available.

Return type:

boolean

Returns:

returns true if PrintToPdf can be performed.

apryse_sdk.PrintToPdfModule_PrintToPdf(pdf_doc, file_to_print, options=None)

Generate a PDF file by printing a document to the Apryse PDF printer via the Windows print verb.

Parameters:

• pdf_doc (PDFDoc) – – The destination document.

• file_to_print (string) – – The source document filename.

• options (PrintToPdfOptions) – – Print options (optional).

class apryse_sdk.PrintToPdfOptions

Bases: object

GetHorizontalPageMargin()

Gets the value HorizontalPageMargin from the options object The horizontal margins (left and right) in points. The default is a 1/4 of an inch or 18 points.

Return type:

double

Returns:

a double, the current value for HorizontalPageMargin.

GetPageHeight()

Gets the value PageHeight from the options object The page height to use in points. If not set (or set to 0), uses letter paper size.

Return type:

double

Returns:

a double, the current value for PageHeight.

GetPageOrientation()

Gets the value PageOrientation from the options object Page orientation, “portrait” or “landscape”.

Return type:

string

Returns:

a string, the current value for PageOrientation.

GetPageWidth()

Gets the value PageWidth from the options object The page width to use in points. If not set (or set to 0), uses letter paper size.

Return type:

double

Returns:

a double, the current value for PageWidth.

GetVerticalPageMargin()

Gets the value VerticalPageMargin from the options object The vertical margins (top and bottom) in points. The default is a 1/4 of an inch or 18 points.

Return type:

double

Returns:

a double, the current value for VerticalPageMargin.

SetHorizontalPageMargin(value)

Sets the value for HorizontalPageMargin in the options object The horizontal margins (left and right) in points. The default is a 1/4 of an inch or 18 points.

Parameters:

value: – the new value for HorizontalPageMargin

Return type:

PrintToPdfOptions

Returns:

this object, for call chaining

SetPageHeight(value)

Sets the value for PageHeight in the options object The page height to use in points. If not set (or set to 0), uses letter paper size.

Parameters:

value: – the new value for PageHeight

Return type:

PrintToPdfOptions

Returns:

this object, for call chaining

SetPageOrientation(value)

Sets the value for PageOrientation in the options object Page orientation, “portrait” or “landscape”.

Parameters:

value: – the new value for PageOrientation

Return type:

PrintToPdfOptions

Returns:

this object, for call chaining

SetPageWidth(value)

Sets the value for PageWidth in the options object The page width to use in points. If not set (or set to 0), uses letter paper size.

Parameters:

value: – the new value for PageWidth

Return type:

PrintToPdfOptions

Returns:

this object, for call chaining

SetVerticalPageMargin(value)

Sets the value for VerticalPageMargin in the options object The vertical margins (top and bottom) in points. The default is a 1/4 of an inch or 18 points.

Parameters:

value: – the new value for VerticalPageMargin

Return type:

PrintToPdfOptions

Returns:

this object, for call chaining

property thisown

The membership flag

apryse_sdk.Print_StartPrintJob(args)

Overload 1:

(Windows Only) Print the PDFDoc to a printer. Depending on the OS and installed libraries, the PDFDoc will be sent using the GDI or the XPS print path. This function will block until the print job is done at the OS level.

Notes: If the printer is grayscale, only grayscale data will be sent.

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to be printed

• in_printerName (string) – the name of the printer to print to

• in_jobName (string) – the name of the job for print queue monitoring, can be empty.

• in_outputFileName (string) – if not empty, the name of the output file to save the printout into. This could be a PostScript, PCL, XPS or other file.

• in_pagesToPrint (PageSet) – a PageSet specifying which pages to print.

• in_printMode – options for the printer, see the PrinterMode class below.

• in_cancel (boolean) – set this to true to cancel the print job.

• in_context (Context) – (Optional) Optional Content Group setting, for example from PDFViewCtrl::GetOCGContext.

Return type:

void

Returns:

void. Throws a trn::Common::Exception on failure.

Overload 2:

(Windows Only) Print the PDFDoc to a printer. Depending on the OS and installed libraries, the PDFDoc will be sent using the GDI or the XPS print path. This function will block until the print job is done at the OS level.

Notes: Same functionality as other StartPrintJob but with char types for printer name, job name, output file name If the printer is grayscale, only grayscale data will be sent.

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to be printed

• in_printerName (string) – the name of the printer to print to

• in_jobName (string) – the name of the job for print queue monitoring, can be empty.

• in_outputFileName (string) – if not empty, the name of the output file to save the printout into. This could be a PostScript, PCL, XPS or other file.

• in_pagesToPrint (PageSet) – a PageSet specifying which pages to print.

• in_printMode – options for the printer, see the PrinterMode class below.

• in_cancel (boolean) – set this to true to cancel the print job.

• in_context (Context) – (Optional) Optional Content Group setting, for example from PDFViewCtrl::GetOCGContext.

Return type:

void

Returns:

void. Throws a trn::Common::Exception on failure.

Overload 3:

(Windows Only) Print the PDFDoc to a printer. Depending on the OS and installed libraries, the PDFDoc will be sent using the GDI or the XPS print path. This function will block until the print job is done at the OS level.

Notes: Same functionality as other StartPrintJob but with char types for printer name, job name, output file name If the printer is grayscale, only grayscale data will be sent.

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to be printed

• in_printerName (string) – the name of the printer to print to

• in_jobName (string) – the name of the job for print queue monitoring, can be empty.

• in_outputFileName (string) – if not empty, the name of the output file to save the printout into. This could be a PostScript, PCL, XPS or other file.

• in_pagesToPrint (PageSet) – a PageSet specifying which pages to print.

• in_printMode – options for the printer, see the PrinterMode class below.

• in_cancel (boolean) – set this to true to cancel the print job.

• in_context – (Optional) Optional Content Group setting, for example from PDFViewCtrl::GetOCGContext.

Return type:

void

Returns:

void. Throws a trn::Common::Exception on failure.

Overload 4:

(Windows Only) Print the PDFDoc to a printer. Depending on the OS and installed libraries, the PDFDoc will be sent using the GDI or the XPS print path. This function will block until the print job is done at the OS level.

Notes: Same functionality as other StartPrintJob but with char types for printer name, job name, output file name If the printer is grayscale, only grayscale data will be sent.

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to be printed

• in_printerName (string) – the name of the printer to print to

• in_jobName (string) – the name of the job for print queue monitoring, can be empty.

• in_outputFileName (string) – if not empty, the name of the output file to save the printout into. This could be a PostScript, PCL, XPS or other file.

• in_pagesToPrint (PageSet) – a PageSet specifying which pages to print.

• in_printMode – options for the printer, see the PrinterMode class below.

• in_cancel – set this to true to cancel the print job.

• in_context – (Optional) Optional Content Group setting, for example from PDFViewCtrl::GetOCGContext.

Return type:

void

Returns:

void. Throws a trn::Common::Exception on failure.

Overload 5:

(Windows Only) Print the PDFDoc to a printer. Depending on the OS and installed libraries, the PDFDoc will be sent using the GDI or the XPS print path. This function will block until the print job is done at the OS level.

Notes: Same functionality as other StartPrintJob but with char types for printer name, job name, output file name If the printer is grayscale, only grayscale data will be sent.

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to be printed

• in_printerName (string) – the name of the printer to print to

• in_jobName (string) – the name of the job for print queue monitoring, can be empty.

• in_outputFileName (string) – if not empty, the name of the output file to save the printout into. This could be a PostScript, PCL, XPS or other file.

• in_pagesToPrint (PageSet) – a PageSet specifying which pages to print.

• in_printMode – options for the printer, see the PrinterMode class below.

• in_cancel – set this to true to cancel the print job.

• in_context – (Optional) Optional Content Group setting, for example from PDFViewCtrl::GetOCGContext.

Return type:

void

Returns:

void. Throws a trn::Common::Exception on failure.

Overload 6:

(Windows Only) Print the PDFDoc to a printer. Depending on the OS and installed libraries, the PDFDoc will be sent using the GDI or the XPS print path. This function will block until the print job is done at the OS level.

Notes: Same functionality as other StartPrintJob but with char types for printer name, job name, output file name If the printer is grayscale, only grayscale data will be sent.

Parameters:

• in_pdfdoc (PDFDoc) – the PDFDoc to be printed

• in_printerName (string) – the name of the printer to print to

• in_jobName (string) – the name of the job for print queue monitoring, can be empty.

• in_outputFileName (string) – if not empty, the name of the output file to save the printout into. This could be a PostScript, PCL, XPS or other file.

• in_pagesToPrint – a PageSet specifying which pages to print.

• in_printMode – options for the printer, see the PrinterMode class below.

• in_cancel – set this to true to cancel the print job.

• in_context – (Optional) Optional Content Group setting, for example from PDFViewCtrl::GetOCGContext.

Return type:

void

Returns:

void. Throws a trn::Common::Exception on failure.

class apryse_sdk.Printer

Bases: object

Convert::Printer is a utility class to install the a printer for print-based conversion of documents for Convert::ToPdf

static GetMode()

Get the current mode for print jobs.

Return type:

int

Returns:

the current print mode

static GetPrinterName()

Get the name of the PDFNet printer installed in this process session.

Return type:

string

Returns:

the Unicode name of the PDFNet printer

Notes: if no printer was installed in this process then the predefined string “PDFTron PDFNet” will be returned.

static Install(args)

Install the PDFNet printer. Installation can take a few seconds, so it is recommended that you install the printer once as part of your deployment process. Duplicated installations will be quick since the presence of the printer is checked before installation is attempted. There is no need to uninstall the printer after conversions, it can be left installed for later access.

Parameters:

in_printerName (string) – the name of the printer to install and use for conversions. If in_printerName is not provided then the name “PDFTron PDFNet” is used.

Notes: Installing and uninstalling printer drivers requires the process to be running as administrator.

static IsInstalled(args)

Determine if the PDFNet printer is installed

Parameters:

in_printerName (string) – the name of the printer to install and use for conversions. If in_printerName is not provided then the name “PDFTron PDFNet” is used.

Return type:

boolean

Returns:

true if the named printer is installed, false otherwise

Notes: may or may not check if the printer with the given name is actually a PDFNet printer.

static SetMode(mode)

Configure how PDFNet prints documents.

Parameters:

mode (int) – set the print mode. Default is e_auto.

static SetPrinterName(args)

Set the name of the PDFNet printer installed in this process session.

Return type:

void

Returns:

the Unicode name of the PDFNet printer

Notes: if no printer was installed in this process then the predefined string “PDFTron PDFNet” will be used.

static Uninstall()

Uninstall all printers using the PDFNet printer driver.

Notes: Installing and uninstalling printer drivers requires the process to be running as administrator. Only the “PDFTron PDFNet” printer can be uninstalled with this function.

e_auto = 0

By default PDFNet will pick the best means of converting the target document.

e_interop_only = 1

For Office file conversions, force COM Interop to be used, regardless if this virtual printer is installed or not.

e_prefer_builtin_converter = 3

For Office file conversions, use the built in converter if it is available for the converted file type.

e_printer_only = 2

For Office file conversions, do not check for Office COM Interop availability, and use the printer path instead.

property thisown

The membership flag

class apryse_sdk.PrinterMode

Bases: object

PrinterMode is a utility class used to represent options for printing.

SetAutoCenter(autoCenter)

Set automatic centering of document pages onto the output pages

Parameters:

autoCenter (boolean) – if true will center document pages onto the output pages. Default is true.

SetAutoRotate(autoRotate)

Set automatic rotation of document pages to best fit the output pages

Parameters:

autoRotate (boolean) – if true will rotate document pages onto the output pages. Default is true.

SetCollation(collation)

Set the collation of the printing, useful for multiple copies

Parameters:

collation (boolean) – if true, pages of copies will be printed 1, 2, 3. if false, then pages of copies will be printed 1, 1, 1, …, 2, 2, 2, … Default is true.

SetCopyCount(copyCount)

Set the number of copies to be printed

Parameters:

copyCount (int) – the number of copies to be printed, must be greater than zero. Default is 1.

SetDPI(dpi)

Set the DPI (dots per inch) of the printing

:param dpi:, 300 is typically laser printer output, 96 dpi is LCD screen

the larger this value the larger the file sent to the printer and the finer the document features that can be resolved. Default is 300.

SetDuplexing(mode)

Set the duplexing mode

Parameters:

mode (int) – one of {e_Duplex_Auto, e_Duplex_None, e_Duplex_LongSide, e_Duplex_ShortSide}. Default is e_Duplex_Auto.

SetNUp(args)

Overload 1:

Set the number of document pages to place on the output pages across and vertically. Pages will be automatically rotated to best fit the page.

Parameters:

• nup (int) – one of {e_NUp_1_1, e_NUp_2_1, e_NUp_2_2, e_NUp_3_2, e_NUp_3_3, e_NUp_4_4}. Default is e_NUp_1_1.

• pageOrder (int) – order of document pages across and down output page. Default is e_PageOrder_LeftToRightThenTopToBottom.

Overload 2:

Set the number of document pages to place on the output pages across and vertically. Pages will be automatically rotated to best fit the page.

Typical values: (2,1) 2-up; (2,2) 4 per page, etc

Parameters:

• x (int) – number of document pages across. Default is 1.

• y (int) – number of document pages down. Default is 1.

• pageOrder (int) – order of document pages across and down output page Default is e_PageOrder_LeftToRightThenTopToBottom.

Overload 3:

Set the number of document pages to place on the output pages across and vertically. Pages will be automatically rotated to best fit the page.

Typical values: (2,1) 2-up; (2,2) 4 per page, etc

Parameters:

• x (int) – number of document pages across. Default is 1.

• y (int) – number of document pages down. Default is 1.

• pageOrder – order of document pages across and down output page Default is e_PageOrder_LeftToRightThenTopToBottom.

SetOrientation(orientation)

Set the orientation of the output document

Parameters:

orientation (int) – {e_Orientation_Portrait, e_Orientation_Landscape} Default is e_Orientation_Portrait.

SetOutputAnnot(printContent)

Set the printing of annotations

Parameters:

printContent (int) – one of {e_PrintContent_DocumentOnly, e_PrintContent_DocumentAndAnnotations}. Default is e_PrintContent_DocumentAndAnnotations.

SetOutputColor(color)

Set the color output of the printing

Parameters:

color (int) – one of {e_OutputColor_Color, e_OutputColor_Grayscale, e_OutputColor_Monochrome}. Default is e_OutputColor_Color.

Notes: If the XPS print path is being used, then the printer spooler file will ignore the grayscale option and be in full color. The printer driver will then perform any color conversions necessary.

SetOutputPageBorder(printBorder)

Set the printing of page borders, helpful when printing multiple document pages per output page

Parameters:

printBorder (boolean) – if true will add a thin frame around each page border. Default is false.

SetOutputQuality(quality)

Set the quality of the printing. Overridden if SetDPI is called.

Parameters:

quality (int) – one of {e_OutputQuality_Draft, e_OutputQuality_Low, e_OutputQuality_Medium, e_OutputQuality_High}. Default is to use DPI of 300.

SetPaperSize(args)

Overload 1:

Set the output printer paper size (assumed to be correct)

Parameters:

size (Rect) – the size of the output paper size in points (72 points = 1 inch). Default is US Letter or Rect(0, 0, 612, 792)

Overload 2:

Set the output printer paper size

Parameters:

paperSize (int) – standard paper size enumerator

SetScale(scale)

Set the scaling of the document pages to the output pages. Causes SetScaleType(e_ScaleType_CustomScale) to be set.

Parameters:

scale (double) – to apply to document pages. 1.0 is no scale, greater than 1.0 increases document page sizes, less than 1.0 reduces document pages sizes on output pages. Default is 1.0

SetScaleType(scaleType)

Set the scaling of the document page to the output pages

Parameters:

scaleType (int) – one of {e_ScaleType_None, e_ScaleType_FitToOutputPage, e_ScaleType_ReduceToOutputPage}. Default is e_ScaleType_None.

SetUseRleImageCompression(useRleImageCompression)

Set whether RLE image compression is used for printing bitmaps

Parameters:

useRleImageCompression (boolean) – if true, printer spool file will be reduced. However, some printers do not support this type of image compression and will produce blank pages. Default is false

e_10x11 = 45

e_10x14 = 16

e_11x17 = 17

e_12x11 = 90

e_15x11 = 46

e_6_3_quarters_envelope = 38

e_9x11 = 44

e_Duplex_Auto = 0

use the current printer setting

e_Duplex_LongSide = 2

flip the paper along the long side

e_Duplex_None = 1

single-sided printing

e_Duplex_ShortSide = 3

flip the paper along the short side

e_NUp_1_1 = 0

1 document page to 1 output page

e_NUp_2_1 = 1

2 document pages to 1 output page

e_NUp_2_2 = 2

2 by 2 document pages to 1 output page

e_NUp_3_2 = 3

3 by 2 document pages to 1 output page

e_NUp_3_3 = 4

3 by 3 document pages to 1 output page

e_NUp_4_4 = 5

4 by 4 document pages to 1 output page

e_Orientation_Landscape = 1

wider than tall

e_Orientation_Portrait = 0

taller than wide

e_OutputColor_Color = 0

24bpp

e_OutputColor_Grayscale = 1

8bpp

e_OutputColor_Monochrome = 2

single color (1bpp)

e_OutputQuality_Draft = -1

printer draft mode

e_OutputQuality_High = -4

printer high quality mode

e_OutputQuality_Low = -2

printer low quality mode

e_OutputQuality_Medium = -3

printer medium quality mode

e_PageOrder_BottomToTopThenLeftToRight = 3

e_PageOrder_LeftToRightThenTopToBottom = 0

e_PageOrder_RightToLeftThenTopToBottom = 1

e_PageOrder_TopToBottomThenLeftToRight = 2

e_PrintContent_DocumentAndAnnotations = 1

e_PrintContent_DocumentAnnotationsAndComments = 2

e_PrintContent_DocumentOnly = 0

e_ScaleType_FitToOutputPage = 1

fit to the output page

e_ScaleType_None = 0

no scaling

e_ScaleType_ReduceToOutputPage = 2

shrink to fit the output page

e_Superb_Superb_a3 = 58

e_a2 = 66

e_a3 = 8

e_a3_extra = 63

e_a3_extra_transverse = 68

e_a3_rotated = 76

e_a3_transverse = 67

e_a4 = 9

e_a4_extra = 53

e_a4_plus = 60

e_a4_rotated = 77

e_a4_small = 10

e_a4_transverse = 55

e_a5 = 11

e_a5_extra = 64

e_a5_rotated = 78

e_a5_transverse = 61

e_a6 = 70

e_a6_rotated = 83

e_b4_iso = 42

e_b4_jis = 12

e_b4_jis_rotated = 79

e_b5_iso_extra = 65

e_b5_jis = 13

e_b5_jis_rotated = 80

e_b5_jis_transverse = 62

e_b6_jis = 88

e_b6_jis_rotated = 89

e_c_size_sheet = 24

e_custom = 0

e_d_size_sheet = 25

e_double_japanese_postcard_rotated = 82

e_e_size_sheet = 26

e_envelope_10 = 20

e_envelope_11 = 21

e_envelope_12 = 22

e_envelope_14 = 23

e_envelope_9 = 19

e_envelope_b4 = 33

e_envelope_b5 = 34

e_envelope_b6 = 35

e_envelope_c3 = 29

e_envelope_c4 = 30

e_envelope_c5 = 28

e_envelope_c6 = 31

e_envelope_c65 = 32

e_envelope_dl = 27

e_envelope_invite = 47

e_envelope_italy = 36

e_envelope_monarch = 37

e_executive = 7

e_folio = 14

e_german_legal_fanfold = 41

e_german_std_fanfold = 40

e_japanese_double_postcard = 69

e_japanese_envelope_chou_3 = 73

e_japanese_envelope_chou_3_rotated = 86

e_japanese_envelope_chou_4 = 74

e_japanese_envelope_chou_4_rotated = 87

e_japanese_envelope_kaku_2 = 71

e_japanese_envelope_kaku_2_rotated = 84

e_japanese_envelope_kaku_3 = 72

e_japanese_envelope_kaku_3_rotated = 85

e_japanese_envelope_you_4 = 91

e_japanese_envelope_you_4_rotated = 92

e_japanese_postcard = 43

e_japanese_postcard_rotated = 81

e_ledger = 4

e_legal = 5

e_legal_extra = 51

e_letter = 1

e_letter_extra = 50

e_letter_extra_transverse = 56

e_letter_plus = 59

e_letter_rotated = 75

e_letter_small = 2

e_letter_transverse = 54

e_note = 18

e_prc_16k = 93

e_prc_16k_rotated = 106

e_prc_32k = 94

e_prc_32k_big = 95

e_prc_32k_big__rotated = 108

e_prc_32k_rotated = 107

e_prc_envelop_1 = 96

e_prc_envelop_10 = 105

e_prc_envelop_10_rotated = 118

e_prc_envelop_1_rotated = 109

e_prc_envelop_2 = 97

e_prc_envelop_2_rotated = 110

e_prc_envelop_3 = 98

e_prc_envelop_3_rotated = 111

e_prc_envelop_4 = 99

e_prc_envelop_4_rotated = 112

e_prc_envelop_5 = 100

e_prc_envelop_5_rotated = 113

e_prc_envelop_6 = 101

e_prc_envelop_6_rotated = 114

e_prc_envelop_7 = 102

e_prc_envelop_7_rotated = 115

e_prc_envelop_8 = 103

e_prc_envelop_8_rotated = 116

e_prc_envelop_9 = 104

e_prc_envelop_9_rotated = 117

e_quarto = 15

e_reserved_48 = 48

e_reserved_49 = 49

e_statement = 6

e_supera_supera_a4 = 57

e_tabloid = 3

e_tabloid_extra = 52

e_us_std_fanfold = 39

property m_printerMode

property thisown

The membership flag

apryse_sdk.Printer_GetMode()

Get the current mode for print jobs.

Return type:

int

Returns:

the current print mode

apryse_sdk.Printer_GetPrinterName()

Get the name of the PDFNet printer installed in this process session.

Return type:

string

Returns:

the Unicode name of the PDFNet printer

Notes: if no printer was installed in this process then the predefined string “PDFTron PDFNet” will be returned.

apryse_sdk.Printer_Install(args)

Install the PDFNet printer. Installation can take a few seconds, so it is recommended that you install the printer once as part of your deployment process. Duplicated installations will be quick since the presence of the printer is checked before installation is attempted. There is no need to uninstall the printer after conversions, it can be left installed for later access.

Parameters:

in_printerName (string) – the name of the printer to install and use for conversions. If in_printerName is not provided then the name “PDFTron PDFNet” is used.

Notes: Installing and uninstalling printer drivers requires the process to be running as administrator.

apryse_sdk.Printer_IsInstalled(args)

Determine if the PDFNet printer is installed

Parameters:

in_printerName (string) – the name of the printer to install and use for conversions. If in_printerName is not provided then the name “PDFTron PDFNet” is used.

Return type:

boolean

Returns:

true if the named printer is installed, false otherwise

Notes: may or may not check if the printer with the given name is actually a PDFNet printer.

apryse_sdk.Printer_SetMode(mode)

Configure how PDFNet prints documents.

Parameters:

mode (int) – set the print mode. Default is e_auto.

apryse_sdk.Printer_SetPrinterName(args)

Set the name of the PDFNet printer installed in this process session.

Return type:

void

Returns:

the Unicode name of the PDFNet printer

Notes: if no printer was installed in this process then the predefined string “PDFTron PDFNet” will be used.

apryse_sdk.Printer_Uninstall()

Uninstall all printers using the PDFNet printer driver.

Notes: Installing and uninstalling printer drivers requires the process to be running as administrator. Only the “PDFTron PDFNet” printer can be uninstalled with this function.

class apryse_sdk.Proxy

Bases: object

Proxy settings to be used when loading content from web pages.

Notes: These Proxy settings will only be used if type is not e_default.

Destroy()

Frees the native memory of the object.

SetHost(host)

Set the proxy host to use.

Parameters:

host (string) –

• String defining the host name, e.g. “myserver” or “www.xxx.yyy.zzz”

SetPassword(password)

Set the password to use when logging into the proxy with username

Parameters:

password (string) –

• The password to use, e.g. “bart”.

SetPort(port)

Set the port number to use

Parameters:

port (int) –

• A valid port number, e.g. 3128.

SetType(type)

SetUsername(username)

Set the username to use when logging into the proxy

Parameters:

username (string) –

• The login name, e.g. “elbarto”.

e_default = 0

e_http = 2

e_none = 1

e_socks5 = 3

property mp_impl

property thisown

The membership flag

class apryse_sdk.PushButtonWidget(args)

Bases: Widget

An object representing a push button used in a PDF Form.

static Create(args)

Overload 1:

Creates a new Push Button Widget annotation, in the specified document.

Parameters:

• doc (PDFDoc) – The document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds, specified in user space coordinates.

• field_name (string) – The name of the field for which to create a PushButton widget.

Return type:

PushButtonWidget

Returns:

A newly created default Push Button Widget annotation.

Overload 2:

Creates a new Widget annotation, in the specified document.

Parameters:

• doc (PDFDoc) – The document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds, specified in user space coordinates.

• field (Field) – the field for which to create a Push Button Widget.

Return type:

PushButtonWidget

Returns:

A newly created default Push Button Widget annotation.

property thisown

The membership flag

apryse_sdk.PushButtonWidget_Create(args)

Overload 1:

Creates a new Push Button Widget annotation, in the specified document.

Parameters:

• doc (PDFDoc) – The document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds, specified in user space coordinates.

• field_name (string) – The name of the field for which to create a PushButton widget.

Return type:

PushButtonWidget

Returns:

A newly created default Push Button Widget annotation.

Overload 2:

Creates a new Widget annotation, in the specified document.

Parameters:

• doc (PDFDoc) – The document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds, specified in user space coordinates.

• field (Field) – the field for which to create a Push Button Widget.

Return type:

PushButtonWidget

Returns:

A newly created default Push Button Widget annotation.

class apryse_sdk.QuadPoint(args)

Bases: object

property p1

property p2

property p3

property p4

property thisown

The membership flag

class apryse_sdk.RadioButtonGroup(args)

Bases: object

An object representing a Group of Radio Buttons that can be used to create new Radio Buttons. If a group contains multiple buttons they will be connected.

Add(args)

Adds a new RadioButtonWidget to the RadioButtonGroup

Parameters:

• pos (Rect) – A rectangle specifying the annotation’s bounds, specified in user space coordinates.

• onstate (string) – The onstate for this button. This will rarely need to be explicitly set. However, it can be used to allow multiple radiobuttons in a group to be on at once if they have the same onstate.

Return type:

RadioButtonWidget

Returns:

A newly created default RadioButtonWidget.

AddGroupButtonsToPage(page)

Add all group buttons to the page

Parameters:

page (Page) – The page in which to add the buttons.

static Create(args)

Creates a new RadioButtonGroup in the specified document.

Parameters:

• doc (PDFDoc) – The document in which the RadioButtonGroup is created.

• field_name (string) – The name of the field to create and use in this RadioButtonGroup.

Return type:

RadioButtonGroup

Returns:

A newly created RadioButtonGroup.

GetButton(index)

Retrieves the button at a given index.

Parameters:

index (int) – The index to use.

Return type:

RadioButtonWidget

Returns:

The RadioButtonWidget at the given index

GetField()

Gets the field associated with this RadioButtonGroup

Return type:

Field

Returns:

The Field associated with this RadioButtonGroup

GetNumButtons()

Gets the number of buttons in this RadioButtonGroup

Return type:

int

Returns:

The number of buttons in this RadioButtonGroup

property thisown

The membership flag

apryse_sdk.RadioButtonGroup_Create(args)

Creates a new RadioButtonGroup in the specified document.

Parameters:

• doc (PDFDoc) – The document in which the RadioButtonGroup is created.

• field_name (string) – The name of the field to create and use in this RadioButtonGroup.

Return type:

RadioButtonGroup

Returns:

A newly created RadioButtonGroup.

class apryse_sdk.RadioButtonWidget(args)

Bases: Widget

An object representing a Radio Button used in a PDF Form.

EnableButton()

Enable the current radio button. Note that this may disable other Radio Buttons in the same group.

GetGroup()

Gets the group to which the current button is connected.

Return type:

RadioButtonGroup

Returns:

The group containing this Radio Button.

IsEnabled()

Determines whether this button is enabled.

Return type:

boolean

Returns:

A boolean value indicating whether the Radio Button is enabled.

property thisown

The membership flag

class apryse_sdk.Rect(args)

Bases: TRN_rect

Rect is a utility class used to manipulate PDF rectangle objects (refer to section 3.8.3 of the PDF Reference Manual).

Rect can be associated with a SDF/Cos rectangle array using Rect(Obj)ructor or later using Rect::Attach(Obj) or Rect::Update(Obj) methods.

Rect keeps a local cache for rectangle points so it is necessary to call Rect::Update() method if the changes to the Rect should be saved in the attached Cos/SDF array.

Notes: - Although rectangles are conventionally specified by their lower-left and upper-right corners, it is acceptable to specify any two diagonally opposite corners.

Attach(obj)

Attach the Cos/SDF object to the Rect.

Parameters:

obj (Obj) –

• underlying Cos/SDF object. Must be an SDF::Array with four

SDF::Number elements.

Contains(x, y)

Determines if the specified point is contained within the rectangular region defined by this Rectangle

Parameters:

• x (double) – horizontal x value of the point to check

• y (double) – vertical y value of the point to check

Return type:

boolean

Returns:

true is the point is in the rectangle, false otherwise.

GetX1()

Return type:

double

Returns:

The horizontal value of lower-left point.

GetX2()

Return type:

double

Returns:

The horizontal value of upper-right point.

GetY1()

Return type:

double

Returns:

The vertical value of lower-left point.

GetY2()

Return type:

double

Returns:

The vertical value of upper-right point.

Height()

Return type:

double

Returns:

rectangle’s height

Inflate(args)

Overload 1:

Expands the rectangle by the specified size, in all directions.

Parameters:

amount (double) – Specifies the amount to increase the rectangle in all directions.

Overload 2:

Expands the rectangle by the specified size, in all directions.

Parameters:

• x (double) – Specifies the amount to increase the rectangle’s Left (x1) and Right (x2) properties.

• y (double) – Specifies the amount to increase the rectangle’s Top (y1) and Bottom (y2) properties.

IntersectRect(rect1, rect2)

Makes a Rect equal to the intersection of two existing rectangles.

Parameters:

• rect1 (Rect) –

  • A Rect object that contains a source rectangle.

• rect2 (Rect) –

  • A Rect object that contains a source rectangle.

Return type:

boolean

Returns:

true if the intersection is not empty; 0 if the intersection is empty.

Notes: The intersection is the largest rectangle contained in both existing rectangles.

Normalize()

Arrange the points in the rectangle so that the first point is the lower-left corner and the second point is the upper-right corner of the rectangle.

Notes: Although rectangles are conventionally specified by their lower-left and upper-right corners, it is acceptable to specify any two diagonally opposite corners.

Set(x1, y1, x2, y2)

Set the coordinates of the rectangle

Parameters:

• x1 (double) – The left-most position of the rect.

• y1 (double) – The bottom-most position of the rect.

• x2 (double) – The right-most position of the rect.

• y2 (double) – The top-most position of the rect. The rect is not attached to any Cos/SDF object.

SetX1(x1)

Set the horizontal value of lower-left point.

Parameters:

x1 (double) – The left-most position of the rect.

SetX2(x2)

Set the horizontal value of upper-right point.

Parameters:

x2 (double) – The right-most position of the rect.

SetY1(y1)

Set the vertical value of lower-left point.

Parameters:

y1 (double) – The bottom-most position of the rect.

SetY2(y2)

Set the vertical value of upper-right point.

Parameters:

y2 (double) – The top-most position of the rect.

Update(args)

Saves changes made to the Rect object in the attached (or specified) SDF/Cos rectangle.

Parameters:

obj (Obj) –

• an optional parameter indicating a SDF array that should be

updated and attached to this Rect. If parameter rect is NULL or is omitted, update is performed on previously attached Cos/SDF rectangle.

Return type:

boolean

Returns:

true if the attached Cos/SDF rectangle array was successfully updated, false otherwise.

Width()

Return type:

double

Returns:

rectangle’s width

property thisown

The membership flag

class apryse_sdk.RectCollection

Bases: object

AddRect(to_add)

Clear()

GetNumRects()

GetRectAt(index)

property thisown

The membership flag

class apryse_sdk.Redaction(args)

Bases: object

Destroy()

Frees the native memory of the object.

property mp_imp

property thisown

The membership flag

class apryse_sdk.RedactionAnnot(args)

Bases: Markup

A redaction annotation (PDF 1.7) identifies content that is intended to be removed from the document. The intent of redaction annotations is to enable the following: a)Content identification. A user applies redact annotations that specify the pieces or regions of content that should be removed. Up until the next step is performed, the user can see, move and redefine these annotations. b)Content removal. The user instructs the viewer application to apply the redact annotations, after which the content in the area specified by the redact annotations is removed. In the removed content’s place, some marking appears to indicate the area has been redacted. Also, the redact annotations are removed from the PDF document. Redaction annotations provide a mechanism for the first step in the redaction process (content identification). This allows content to be marked for redaction in a non-destructive way, thus enabling a review process for evaluating potential redactions prior to removing the specified content. Redaction annotations shall provide enough information to be used in the second phase of the redaction process (content removal). This phase is application-specific and requires the conforming reader to remove all content identified by the redaction annotation, as well as the annotation itself. Conforming readers that support redaction annotations shall provide a mechanism for applying content removal, and they shall remove all traces of the specified content. If a portion of an image is contained in a redaction region, that portion of the image data shall be destroyed; clipping or image masks shall not be used to hide that data. Such conforming readers shall also be diligent in their consideration of all content that can exist in a PDF document, including XML Forms Architecture (XFA) content and Extensible Metadata Platform (XMP) content.

static Create(doc, pos)

Creates a new Redaction annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds, in user space coordinates.

Return type:

RedactionAnnot

Returns:

A newly created blank Circle annotation.

static CreateAnnot(doc, pos)

GetAppFormXO()

Returns Overlay appearance of the Redaction annotation.

Return type:

Obj

Returns:

An SDF object that represents the overlay appearance of the Redaction annotation.

Notes: This object is a form XObject specifying the overlay appearance for this redaction annotation. After this redaction is applied and the affected content has been removed, the overlay appearance should be drawn such that its origin lines up with the lower-left corner of the annotation rectangle. This form XObject is not necessarily related to other annotation appearances, and may or may not be present in the Appearance dictionary. This entry takes precedence over the Interior Color(IC), OverlayText, OverlayTextAppearance(DA), and QuadPoint(Q) entries.

GetOverlayText()

Returns Overlay text of the Redaction annotation.

Return type:

string

Returns:

A string containing the overlay text of the annotation.

Notes: The OverlayText string is a text string specifying the overlay text that should be drawn over the redacted region after the affected content has been removed. This entry is ignored if the Overlay appearance(RO) entry is present.

GetOverlayTextAppearance()

Returns Overlay text appearance of the Redaction annotation.

Return type:

string

Returns:

A string containing the overlay text appearance of the annotation.

Notes: The overlay text appearance is the appearance string to be used in formatting the overlay text when it is drawn after the affected content has been removed. This entry is ignored if the Overlay appearance stream (RO) entry is present.

GetQuadForm()

Returns Overlay text quadding(justification) format of the Redaction annotation.

Return type:

int

Returns:

A value of the “QuadForm” enum type, indicating the overlay text quadding(justification) format of the Redaction annotation’s overlay text.

GetQuadPoint(idx)

Returns the QuadPoint located at a certain index of the QuadPoint array of the Redaction annotation.

Parameters:

idx (int) – The index of the QuadPoint, starts at zero and must be less than return value of GetQuadPointCount().

Return type:

QuadPoint

Returns:

The QuadPoint located at a certain index of the QuadPoint array of the Redaction annotation.

Notes: An array of n QuadPoints that denote the content region that is intended to be removed. If quad points are not present, the Rect entry denotes the content region that is intended to be removed.

GetQuadPointCount()

Returns the number of QuadPoints in the QuadPoints array of the Redaction annotation.

Return type:

int

Returns:

The number of QuadPoints.

Notes: An array of n QuadPoints that denote the content region that is intended to be removed. If quad points are not present, the Rect entry denotes the content region that is intended to be removed.

GetUseRepeat()

Returns the option of whether to use repeat for the Redaction annotation.

Return type:

boolean

Returns:

A bool indicating whether to repeat for the Redaction annotation.

Notes: If userepeat value is true, then the text specified by OverlayText should be repeated to fill the redacted region after the affected content has been removed. This entry is ignored if the Overlay appearance stream (RO) entry is present. Default value: false.

SetAppFormXO(formxo)

Sets Overlay appearance of the Redaction annotation. (Optional)

Parameters:

formxo (Obj) – An SDF object that represents the overlay appearance of the Redaction annotation.

Notes: This object is a form XObject specifying the overlay appearance for this redaction annotation. After this redaction is applied and the affected content has been removed, the overlay appearance should be drawn such that its origin lines up with the lower-left corner of the annotation rectangle. This form XObject is not necessarily related to other annotation appearances, and may or may not be present in the Appearance dictionary. This entry takes precedence over the Interior Color(IC), OverlayText, OverlayTextAppearance(DA), and QuadPoint(Q) entries.

SetOverlayText(title)

Sets Overlay text of the Redaction annotation.

Parameters:

title (string) – A string containing the overlay text of the annotation.

Notes: The OverlayText string is a text string specifying the overlay text that should be drawn over the redacted region after the affected content has been removed. This entry is ignored if the Overlay appearance stream (RO) entry is present.

SetOverlayTextAppearance(app)

Sets Overlay text appearance of the Redaction annotation.

Parameters:

app (string) – A string containing the overlay text appearance of the annotation.

Notes: The overlay text appearance is the appearance string to be used in formatting the overlay text when it is drawn after the affected content has been removed. This entry is ignored if the Overlay appearance stream (RO) entry is present.

SetQuadForm(args)

Sets Overlay text quadding (justification) format of the Redaction annotation.

Parameters:

form (int) – A value of the “QuadForm” enum type, indicating the overlay text quadding(justification) format of the Redaction annotation.

Notes: Quadding format specifies the form of justification to be used in displaying the overlay text. form=e_LeftJustified

SetQuadPoint(idx, qp)

Set the QuadPoint to be located at a certain index of the QuadPoint array of the Redaction annotation. (Optional; PDF 1.6 )

Parameters:

• idx (int) – The index position where the QuadPoint of interest is to be inserted, starting at 0.

• qp (QuadPoint) – The QuadPoint to be inserted at that position.

Notes: For orientation purposes, the bottom of a quadrilateral is the line formed by p1 and p2 of the QuadPoint. QuadPoints shall be ignored if any coordinate in the array lies outside the region specified by Rect.

SetUseRepeat(userepeat=False)

Sets the option of whether to use repeat for the Redaction annotation.

Parameters:

userepeat (boolean) – A bool indicating whether to repeat for the Redaction annotation.

Notes: If userepeat value is true, then the text specified by OverlayText should be repeated to fill the redacted region after the affected content has been removed. This entry is ignored if the Overlay appearance stream (RO) entry is present. userepeat = false.

e_Centered = 1

Overlay text is centered

e_LeftJustified = 0

Overlay text is left justified

e_None = 3

No justification to the overlay text.

e_RightJustified = 2

Overlay text is right justified

property thisown

The membership flag

apryse_sdk.RedactionAnnot_Create(doc, pos)

Creates a new Redaction annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds, in user space coordinates.

Return type:

RedactionAnnot

Returns:

A newly created blank Circle annotation.

apryse_sdk.RedactionAnnot_CreateAnnot(doc, pos)

class apryse_sdk.Redactor

Bases: object

PDF Redactor is a separately licensable Add-on that offers options to remove (not just covering or obscuring) content within a region of PDF. With printed pages, redaction involves blacking-out or cutting-out areas of the printed page. With electronic documents that use formats such as PDF, redaction typically involves removing sensitive content within documents for safe distribution to courts, patent and government institutions, the media, customers, vendors or any other audience with restricted access to the content.

The redaction process in PDFNet consists of two steps:

1. Content identification: A user applies redact annotations that specify the

pieces or regions of content that should be removed. The content for redaction can be identified either interactively (e.g. using ‘pdftron.PDF.PDFViewCtrl’ as shown in PDFView sample) or programmatically (e.g. using ‘pdftron.PDF.TextSearch’ or ‘pdftron.PDF.TextExtractor’). Up until the next step is performed, the user can see, move and redefine these annotations.

2. Content removal: Using ‘pdftron.PDF.Redactor.Redact()’ the user instructs

PDFNet to apply the redact regions, after which the content in the area specified by the redact annotations is removed. The redaction function includes number of options to control the style of the redaction overlay (including color, text, font, border, transparency, etc.).

PDFTron Redactor makes sure that if a portion of an image, text, or vector graphics is contained in a redaction region, that portion of the image or path data is destroyed and is not simply hidden with clipping or image masks. PDFNet API can also be used to review and remove metadata and other content that can exist in a PDF document, including XML Forms Architecture (XFA) content and Extensible Metadata Platform (XMP) content.

static Redact(args)

property thisown

The membership flag

apryse_sdk.Redactor_Redact(args)

class apryse_sdk.RefreshOptions

Bases: object

GetDrawBackgroundOnly()

Gets the value DrawBackgroundOnly from the options object If true draw only the background and border, which can be useful when generating the rest of the annotation content elsewhere. Off by default.

Return type:

boolean

Returns:

the current value for DrawBackgroundOnly.

GetInternalObj()

GetRefreshExisting()

Gets the value RefreshExisting from the options object Whether we should refresh annotations with existing appearances. Defaults to false when used in PDFDoc.RefreshAnnotAppearances and true when used in Annot.RefreshAppearance.

Return type:

boolean

Returns:

the current value for RefreshExisting.

GetUseNonStandardRotation()

Gets the value UseNonStandardRotation from the options object Whether we should use rotation in the annotation even if it is not a multiple of 90. Off by default.

Return type:

boolean

Returns:

the current value for UseNonStandardRotation.

GetUseRoundedCorners()

Gets the value UseRoundedCorners from the options object Whether we should use the corner radii specified in Annot.BorderStyle. Off by default.

Return type:

boolean

Returns:

the current value for UseRoundedCorners.

SetDrawBackgroundOnly(value)

Sets the value for DrawBackgroundOnly in the options object If true draw only the background and border, which can be useful when generating the rest of the annotation content elsewhere. Off by default.

Parameters:

value (boolean) – the new value for DrawBackgroundOnly

Return type:

RefreshOptions

Returns:

this object, for call chaining

SetRefreshExisting(value)

Sets the value for RefreshExisting in the options object Whether we should refresh annotations with existing appearances. Defaults to false when used in PDFDoc.RefreshAnnotAppearances and true when used in Annot.RefreshAppearance.

Parameters:

value (boolean) – the new value for RefreshExisting

Return type:

RefreshOptions

Returns:

this object, for call chaining

SetUseNonStandardRotation(value)

Sets the value for UseNonStandardRotation in the options object Whether we should use rotation in the annotation even if it is not a multiple of 90. Off by default.

Parameters:

value (boolean) – the new value for UseNonStandardRotation.

Return type:

RefreshOptions

Returns:

this object, for call chaining

SetUseRoundedCorners(value)

Sets the value for UseRoundedCorners in the options object Whether we should use the corner radii specified in Annot.BorderStyle. Off by default.

Parameters:

value (boolean) – the new value for UseRoundedCorners.

Return type:

RefreshOptions

Returns:

this object, for call chaining

property thisown

The membership flag

class apryse_sdk.ResultSnapshot(args)

Bases: object

The class ResultSnapshot. Represents a transition between two document states.

CurrentState()

Retrieves the document state to which this transition has transitioned.

Return type:

DocSnapshot

Returns:

The current document state.

Destroy()

IsNullTransition()

Returns whether this transition is a null transition.

Return type:

boolean

Returns:

Whether this transition is a null transition.

IsOk()

Returns whether this transition is valid or a null transition.

Return type:

boolean

Returns:

Whether this transition is valid or a null transition.

PreviousState()

Retrieves the document state from which this transition has transitioned.

Return type:

DocSnapshot

Returns:

The previous document state.

property m_impl

property thisown

The membership flag

class apryse_sdk.RoleMap(args)

Bases: object

RoleMap is a dictionary that maps the names of structure types used in the document to their approximate equivalents in the set of standard structure types.

GetDirectMap(type)

Return type:

string

Returns:

The direct mapping of given StructElement type, or NULL if such mapping is not defined.

Parameters:

type (string) – element type

GetSDFObj()

Returns the RoleMap dictionary.

Return type:

Obj

Returns:

the object to the underlying SDF/Cos dictionary.

IsValid()

Return type:

boolean

Returns:

true if this is a valid (non-null) RoleMap, false otherwise. If the function returns false the underlying SDF/Cos object is null or is not valid and the RoleMap should be treated as NULL object.

property thisown

The membership flag

class apryse_sdk.RubberStamp(args)

Bases: Markup

A RubberStamp annotation displays text or graphics intended to look as if they were stamped on the page with a rubber stamp.

static Create(args)

Overload 1:

Creates a new RubberStamp annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds in default user space units.

Return type:

RubberStamp

Returns:

A newly created blank RubberStamp annotation.

Overload 2:

Creates a new RubberStamp annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds in default user space units.

• form_xobject (Obj) –

  An object specifying a custom appearance for the annotation, containing TEXT as string (mandatory): The text to be displayed in rubber stamp TEXT_BELOW as string (optional): The text to be displayed below the first text FILL_COLOR as an array of three or four numbers between 0.0 to 1.0 (optional): The fill color TEXT_COLOR as an array of three or four numbers between 0.0 to 1.0 (optional): The text color BORDER_COLOR as an array of three or four numbers between 0.0 to 1.0 (optional): The border color FILL_COLOR_START as an array of three or four numbers between 0.0 to 1.0 (optional):

  The start fill color if background is gradient

  FILL_COLOR_END as an array of three or four numbers between 0.0 to 1.0 (optional):

  The end fill color if background is gradient

  FILL_OPACITY as a number (optional): the fill opacity TEXT_OPACITY as a number (optional): the text opacity ROTATION as a number (optional): rotation. valid numbers are {0, 90, 180, 270} POINTING_LEFT as a boolean (optional): if the stamp is pointing left POINTING_RIGHT as a boolean (optional): if the stamp is pointing right

Return type:

RubberStamp

Returns:

A newly created RubberStamp annotation.

static CreateAnnot(args)

GetIcon()

Returns the type of the icon associated with the RubberStamp annotation.

Return type:

int

Returns:

A value of enum “Icon” that represents the type of icon associated with the annotation. Default value: e_Draft.

GetIconName()

Returns the name of the icon associated with the RubberStamp annotation.

Return type:

string

Returns:

A string that is the name of the icon associated with the RubberStamp annotation.

Notes: The following icon names are equivalent to predefined icon types from the enum “Icon”: “Approved” = e_Approved “Experimental” = e_Experimental “NotApproved” = e_NotApproved “AsIs” = e_AsIs “Expired” = e_Expired “NotForPublicRelease” = e_NotForPublicRelease “Confidential” = e_Confidential “Final” = e_Final “Sold” = e_Sold “Departmental” = e_Departmental “Format” = e_ForComment “TopSecret” = e_TopSecret “ForPublicRelease” = e_ForPublicRelease “Draft” = e_Draft “Unknown” = e_Unknown Names other than mentioned above do not have predefined icon appearances.

SetIcon(args)

Overload 1:

Sets the type of the icon associated with the RubberStamp annotation.

Parameters:

type (int) – A value of enum “Icon” type that represents the type of icon associated with the annotation. Default value: e_Draft.

Overload 2:

Sets the name of the icon associated with the RubberStamp annotation.

Parameters:

iconstring – the name of the icon associated with the RubberStamp annotation.

Notes: The following icon names are equivalent to predefined icon types from the enum “Icon”: “Approved” = e_Approved “Experimental” = e_Experimental “NotApproved” = e_NotApproved “AsIs” = e_AsIs “Expired” = e_Expired “NotForPublicRelease” = e_NotForPublicRelease “Confidential” = e_Confidential “Final” = e_Final “Sold” = e_Sold “Departmental” = e_Departmental “Format” = e_ForComment “TopSecret” = e_TopSecret “ForPublicRelease” = e_ForPublicRelease “Draft” = e_Draft “Unknown” = e_Unknown Names other than mentioned above do not have predefined icon appearances.

SetOpacity(opacity)

Updates the appearance of the stamp with the given opacity value Opacity value does not accumulate in case of subsequent calls - i.e. last call sets the final opacity

e_Approved = 0

a stamp with the text “Approved”.

e_AsIs = 3

a stamp with the text “As Is”.

e_Confidential = 6

a stamp with the text “Confidential”.

e_Departmental = 9

a stamp with the text “Departmental”.

e_Draft = 13

a stamp with the text “Draft”.

e_Experimental = 1

a stamp with the text “Experimental”.

e_Expired = 4

a stamp with the text “Expired”.

e_Final = 7

a stamp with the text “Final”.

e_ForComment = 10

a stamp with the text “For Comment”.

e_ForPublicRelease = 12

a stamp with the text “For Public Release”.

e_NotApproved = 2

a stamp with the text “Not Approved”.

e_NotForPublicRelease = 5

a stamp with the text “Not For Public Release”.

e_Sold = 8

a stamp with the text “Sold”.

e_TopSecret = 11

a stamp with the text “Top Secret”.

e_Unknown = 14

Non-standard or user defined stamp.

property thisown

The membership flag

apryse_sdk.RubberStamp_Create(args)

Overload 1:

Creates a new RubberStamp annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds in default user space units.

Return type:

RubberStamp

Returns:

A newly created blank RubberStamp annotation.

Overload 2:

Creates a new RubberStamp annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds in default user space units.

• form_xobject (Obj) –

  An object specifying a custom appearance for the annotation, containing TEXT as string (mandatory): The text to be displayed in rubber stamp TEXT_BELOW as string (optional): The text to be displayed below the first text FILL_COLOR as an array of three or four numbers between 0.0 to 1.0 (optional): The fill color TEXT_COLOR as an array of three or four numbers between 0.0 to 1.0 (optional): The text color BORDER_COLOR as an array of three or four numbers between 0.0 to 1.0 (optional): The border color FILL_COLOR_START as an array of three or four numbers between 0.0 to 1.0 (optional):

  The start fill color if background is gradient

  FILL_COLOR_END as an array of three or four numbers between 0.0 to 1.0 (optional):

  The end fill color if background is gradient

  FILL_OPACITY as a number (optional): the fill opacity TEXT_OPACITY as a number (optional): the text opacity ROTATION as a number (optional): rotation. valid numbers are {0, 90, 180, 270} POINTING_LEFT as a boolean (optional): if the stamp is pointing left POINTING_RIGHT as a boolean (optional): if the stamp is pointing right

Return type:

RubberStamp

Returns:

A newly created RubberStamp annotation.

apryse_sdk.RubberStamp_CreateAnnot(args)

class apryse_sdk.SDFDoc(args)

Bases: object

SDFDoc is a low-level document representing a graph of SDF::Obj nodes that can be used to build higher-level document models such as PDF (Portable Document Format) or FDF (Forms Document Format).

SDFDoc brings together document security, document utility methods, and all SDF objects.

A SDF document can be created from scratch using a defaultructor:

SDFDoc mydoc; Obj trailer = mydoc.GetTrailer();

SDF document can be also created from an existing file (e.g. an external PDF document):

SDFDoc mydoc("in.pdf");
Obj trailer = mydoc.GetTrailer();

or from a memory buffer or some other Filter/Stream such as a HTTP Filter connection:

MemoryFilter memory = ....
SDFDoc mydoc(memory);
Obj trailer = mydoc.GetTrailer();

Finally SDF document can be accessed from a high-level PDF document as follows:

PDFDoc doc("in.pdf");
SDFDoc mydoc = doc.GetSDFDoc();
Obj trailer = mydoc.GetTrailer();

Note that the examples above used doc.GetTrailer() in order to access document trailer, the starting SDF object (root node) in every document. Following the trailer links, it is possible to visit all low-level objects in a document (e.g. all pages, outlines, fonts, etc).

SDFDoc also provides utility methods used to import objects and object collections from one document to another. These methods can be useful for copy operations between documents such as a high-level page merge and document assembly.

ClearMarks()

Removes ‘marked’ flag from all objects in cross reference table.

Close()

Close SDFDoc

CreateIndirectArray()

Used to create SDF/Cos indirect object.

Unlike direct objects, indirect objects can be referenced by more than one object (i.e. indirect objects they can be shared).

Notes: In C++ doc.CreateIndirect???(…) is equivalent to ???::CreateIndirect(…).

CreateIndirectBool(value)

Used to create SDF/Cos indirect object.

Unlike direct objects, indirect objects can be referenced by more than one object (i.e. indirect objects they can be shared).

Parameters:

value (boolean) –

• indirect boolean to create.

Notes: In C++ doc.CreateIndirect???(…) is equivalent to ???::CreateIndirect(…).

CreateIndirectDict()

CreateIndirectName(name)

Used to create SDF/Cos indirect object.

Unlike direct objects, indirect objects can be referenced by more than one object (i.e. indirect objects they can be shared).

Parameters:

name (string) –

• indirectchar object to create.

Notes: In C++ doc.CreateIndirect???(…) is equivalent to ???::CreateIndirect(…).

CreateIndirectNull()

CreateIndirectNumber(value)

CreateIndirectStream(args)

CreateIndirectString(args)

static CreateInternal(impl)

EnableDiskCaching(use_cache_flag)

A document uses a temporary file which is used to cache the contents of any new stream object created in the document (that is the default behavior).

Parameters:

use_cache_flag (boolean) –

• true to enable caching, false to disable caching.

Use this function to enable or disable this feature dynamically.

GetFileName()

Return type:

string

Returns:

The filename of the document if the document is loaded from disk, or empty string if the document is not yet saved or is loaded from a memory buffer.

GetHandleInternal()

GetHeader()

Return type:

string

Returns:

the header string identifying the document version to which the file conforms. For a file conforming to PDF version 1.4, the header should be %PDF-1.4. In general header strings have the following syntax: %AAA-N.n where AAA identifies document specification (such as PDF, FDF, PJTF etc), N is the major version and n is the minor version. The new header string can be set during a full save (see SDFDoc::Save()). For a document that is not serialized the function returns an empty string.

GetHintStream()

Returns document’s initial linearization hint stream if it is available.

Return type:

Obj

Returns:

• the linearization hint stream of the original document or NULL

if the hint stream is not available.

GetLinearizationDict()

Returns document’s initial linearization dictionary if it is available.

Return type:

Obj

Returns:

• the linearization dictionary of the original document or NULL

if the dictionary is not available.

GetObj(obj_num)

Parameters:

obj_num (int) –

• object number of the object to retrieve.

Return type:

Obj

Returns:

• the latest version of the object matching specified object number.

Raises:

• exception is thrown if the object is not found.

GetSecurityHandler()

Return type:

SecurityHandler

Returns:

Currently selected SecurityHandler.

Notes: InitSecurityHandler() should be called before GetSecurityHandler() in order to initialize the handler.

Returned security handler can be modified in order to change the security settings of the existing document. Changes to the current handler will not invalidate the access to the original file and will take effect during document Save().

If the security handler is modified, document will perform a full save even if e_incremental was given as a flag in Save() method.

GetTrailer()

Return type:

Obj

Returns:

• A dictionary representing the root of the document (i.e.

a document trailer dictionary)

HasRepairedXRef()

Checks whether or not the underlying file has an XRef table that had to be repaired when the file was opened. If the document had an invalid XRef table when opened, PDFNet will have repaired the XRef table for its working representation of the document.

Return type:

boolean

Returns:

• true if document was found to be corrupted, and was repaired, during

opening and has not been saved since.

Notes: - If this function returns true, it is not possible to incrementally save the document (see http://www.pdftron.com/kb_corrupt_xref)

ImportObj(obj, deep_copy)

Parameters:

• obj (Obj) –

  • an object to import.

• deep_copy (boolean) –

  • a boolean indicating whether to perform a deep or shallow copy.

  In case of shallow copy all indirect references will be set to null.

If the object belongs to a document the function will perform deep or shallow clone depending whether deep_copy flag was specified.

If the object does not belong to any document ImportObj does not take the object ownership. ImportObj copies the source object and it is users responsibility to delete free objects.

Return type:

Obj

Returns:

• a pointer to the root indirect object in this document

ImportObjs(args)

Overload 1:

The function performs a deep copy of all objects specified in the ‘obj_list’. If objects in the list are directly or indirectly referring to the same object/s, only one copy of the shared object/s will be copied. Therefore, unlike repeated calls to ImportObj, this method will import only one copy of shared objects (objects representing an intersection of graphs specified through ‘obj_list’ of root pointers.

Notes: - All object in the import list must belong to the same source document. - The function does not perform the shallow copy since ImportObj() can be used instead.

Parameters:

obj_list (std::vector< SDF::Obj,std::allocator< SDF::Obj > >) –

• a list of root objects to import. All directly or indirectly objects will be

imported as well.

Return type:

std::vector< SDF::Obj,std::allocator< SDF::Obj > >

Returns:

• a list of imported root objects in this document.

Overload 2:

The function performs a deep copy of all objects specified in the ‘obj_list’. If objects in the list are directly or indirectly referring to the same object/s, only one copy of the shared object/s will be copied. Therefore, unlike repeated calls to ImportObj, this method will import only one copy of shared objects (objects representing an intersection of graphs specified through ‘obj_list’ of root pointers.

Notes: - All object in the import list must belong to the same source document. - The function does not perform the shallow copy since ImportObj() can be used instead.

Parameters:

• obj_list (std::vector< SDF::Obj,std::allocator< SDF::Obj > >) –

  • a list of root objects to import. All directly or indirectly objects will be

  imported as well.

• exclude_list (std::vector< SDF::Obj,std::allocator< SDF::Obj > >) –

  • a list of objects to not include in the deep copy.

Return type:

std::vector< SDF::Obj,std::allocator< SDF::Obj > >

Returns:

• a list of imported root objects in this document.

InitSecurityHandler()

Initializes document’s SecurityHandler. This version of InitSecurityHandler() works with Standard and Custom PDF security and can be used in situations where the password is obtained dynamically via user feedback. See EncTest sample for example code.

This function should be called immediately after an encrypted document is opened. The function does not have any side effects on documents that are not encrypted.

If the security handler was successfully initialized it can be later obtained using GetSecurityHandler() method.

Raises:

An exception is thrown if the matching handler for document’s security was not found in the global SecurityManager. In this case, you need to register additional custom security handlers with the global SecurityManager (using SecurityManagerSingleton).

Return type:

boolean

Returns:

true if the SecurityHandler was successfully initialized (this may include authentication data collection, verification etc.), false otherwise.

Parameters:

custom_data – An optional parameter used to specify custom data that should be passed in SecurityHandler::Initialize() callback.

InitStdSecurityHandler(args)

Overload 1:

Initializes document’s SecurityHandler using the supplied password. This version of InitSecurityHandler() assumes that document uses Standard security and that a password is specified directly.

This function should be called immediately after an encrypted document is opened. The function does not have any side effects on documents that are not encrypted.

If the security handler was successfully initialized, it can be later obtained using GetSecurityHandler() method.

Return type:

boolean

Returns:

true if the given password successfully unlocked the document, false otherwise.

Raises:

An exception is thrown if the document’s security Filter is not ‘Standard’. In this case, you need to register additional custom security handlers with the global SecurityManager (SecurityManagerSingleton).

Parameters:

• password (string) – Specifies the password used to open the document without any user feedback. If you would like to dynamically obtain the password, you need to derive a custom class from StdSecurityHandler() and use InitSecurityHandler() without any parameters. See EncTest sample for example code.

• password_sz (int) – An optional parameter used to specify the size of the password buffer, in bytes. If the ‘password_sz’ is 0, or if the parameter is not specified, the function assumes that the string is null terminated.

Remarks: Deprecated. Use versions that accepts UString or buffer instead.

Overload 2:

Initializes document’s SecurityHandler using the supplied password. This version of InitSecurityHandler() assumes that document uses Standard security and that a password is specified directly.

This function should be called immediately after an encrypted document is opened. The function does not have any side effects on documents that are not encrypted.

If the security handler was successfully initialized, it can be later obtained using GetSecurityHandler() method.

Parameters:

password (string) – Specifies the password used to open the document without any user feedback. If you would like to dynamically obtain the password, you need to derive a custom class from StdSecurityHandler() and use InitSecurityHandler() without any parameters. See EncTest sample for example code.

Return type:

boolean

Returns:

true if the given password successfully unlocked the document, false otherwise.

Raises:

An exception is thrown if the document’s security Filter is not ‘Standard’. In this case, you need to register additional custom security handlers with the global SecurityManager (SecurityManagerSingleton).

Overload 3:

Initializes document’s SecurityHandler using the supplied password. This version of InitSecurityHandler() assumes that document uses Standard security and that a password is specified directly.

This function should be called immediately after an encrypted document is opened. The function does not have any side effects on documents that are not encrypted.

If the security handler was successfully initialized, it can be later obtained using GetSecurityHandler() method.

Parameters:

password_buf (std::vector< int,std::allocator< int > >) – Specifies the password used to open the document without any user feedback. If you would like to dynamically obtain the password, you need to derive a custom class from StdSecurityHandler() and use InitSecurityHandler() without any parameters. See EncTest sample for example code.

Return type:

boolean

Returns:

true if the given password successfully unlocked the document, false otherwise.

Raises:

An exception is thrown if the document’s security Filter is not ‘Standard’. In this case, you need to register additional custom security handlers with the global SecurityManager (SecurityManagerSingleton).

IsEncrypted()

Return type:

boolean

Returns:

true if the document is/was originally encrypted false otherwise.

IsFullSaveRequired()

Return type:

boolean

Returns:

• true if the document requires full save.

IsLinearized()

Call this function to determine whether the document is represented in linearized (fast web view) format.

Return type:

boolean

Returns:

• true if document is stored in fast web view format, false otherwise.

Notes: any changes to the document can invalidate linearization. The function will return ‘true’ only if the original document is linearized and if it is not modified.

In order to provide good performance over relatively slow communication links, PDFNet can generate PDF documents with linearized objects and hint tables that can allow a PDF viewer application to download and view one page of a PDF file at a time, rather than requiring the entire file (including fonts and images) to be downloaded before any of it can be viewed.

To save a document in linearized (fast web view) format you only need to pass ‘SDFDoc.SaveOptions.e_linearized’ flag in the Save method.

IsModified()

Return type:

boolean

Returns:

• true if document was modified, false otherwise

Lock()

Locks the document to prevent competing threads from accessing the document at the same time. Threads attempting to access the document will wait in suspended state until the thread that owns the lock calls doc.Unlock().

LockRead()

Locks the document to prevent competing write threads (using Lock()) from accessing the document at the same time. Other reader threads however, will be allowed to access the document. Threads attempting to obtain write access to the document will wait in suspended state until the thread that owns the lock calls doc.UnlockRead(). Note: To avoid deadlocks obtaining a write lock while holding a read lock is not permitted and will throw an exception. If this situation is encountered please either unlock the read lock before the write lock is obtained or acquire a write lock (rather than read lock) in the first place.

RemoveSecurity()

This function removes document security.

Save(args)

Overload 1:

Saves the document to a file.

If a full save is requested to the original path, the file is saved to a file system-determined temporary file, the old file is deleted, and the temporary file is renamed to path.

A full save with remove unused or linearization option may re-arrange object in the cross reference table. Therefore all pointers and references to document objects and resources should be re acquired in order to continue document editing.

In order to use incremental save the specified path must match original path and e_incremental flag bit should be set.

Parameters:

• path (string) –

  • The full path name to which the file is saved.

• flags (int) –

  • A bit field composed of an OR of the SDFDoc::SaveOptions values.

• header (string) –

  • File header. A new file header is set only during full save.

Raises:

• if the file can’t be opened for saving or if there is a problem during Save

an Exception object will be thrown.

Notes: - Save will modify the SDFDoc object’s internal representation. As such,

the user should acquire a write lock before calling save.

Overload 2:

Saves the document to a memory buffer.

Parameters:

• flags (int) –

  • A bit field composed of an OR of the SDFDoc::SaveOptions values.

  Note that this method ignores e_incremental flag.

• header (string) –

  • File header. A new file header is set only during full save.

Return type:

std::vector< unsigned char,std::allocator< unsigned char > >

Returns:

the buffer containing the serialized version of the document.

Raises:

• if there is a problem during Save an Exception object will be thrown.

Notes: - Save will modify the SDFDoc object’s internal representation. As such,

the user should acquire a write lock before calling save.

Overload 3:

Saves the document to a stream.

Parameters:

• stream (Filter) – The output stream where to write data.

• flags (int) –

  • A bit field composed of an OR of the SDFDoc::SaveOptions values.

• header (string) –

  • File header. A new file header is set only during full save. See also GetHeader()

Raises:

• if there is a problem during Save an Exception object will be thrown.

Notes: - Save will modify the SDFDoc object’s internal representation. As such,

the user should acquire a write lock before calling save.

SetSecurityHandler(handler)

The function sets a new SecurityHandler as the current security handler.

Parameters:

handler (SecurityHandler) –

• new SecurityHandler

Notes: Setting a new security handler will not invalidate the access to the original file and will take effect during document Save().

If the security handler is modified, document will perform a full save even if e_incremental was given as a flag in Save() method.

Swap(obj_num1, obj_num2)

Sometimes it is desirable to modify all indirect references to a given indirect object. It would be inefficient to manually search for all indirect references to a given indirect object.

A more efficient and less error prone method is to replace the indirect object in the cross reference table with a new object. This way the object that is referred to is modified (or replaced) and indirect references do not have to be changed.

Parameters:

• obj_num1 (int) –

  • object number of first object to be swapped.

• obj_num2 (int) –

  • object number of second object to be swapped.

Raises:

the function throws exception in case the swap can’t be performed.

TryLock(milliseconds=0)

Try locking the document, waiting no longer than specified number of milliseconds.

Parameters:

milliseconds (int) –

• max number of milliseconds to wait for the document to lock

Return type:

boolean

Returns:

true if the document is locked for multi-threaded access, false otherwise.

TryLockRead(milliseconds=0)

Try locking the document, waiting no longer than specified number of milliseconds.

Parameters:

milliseconds (int) –

• max number of milliseconds to wait for the document to lock

Return type:

boolean

Returns:

true if the document is locked for multi-threaded access, false otherwise.

Unlock()

Removes the lock from the document.

UnlockRead()

Removes the lock from the document.

XRefSize()

Return type:

int

Returns:

• The size of cross reference table

e_compatibility = 32

e_hex_strings = 4

e_incremental = 1

e_linearized = 16

e_omit_xref = 8

e_remove_unused = 2

property mp_doc

property thisown

The membership flag

apryse_sdk.SDFDoc_CreateInternal(impl)

class apryse_sdk.SElement(args)

Bases: object

SElement represents PDF structural elements, which are nodes in a tree structure, defining a PDF document’s logical structure.

Unlike the StructTree, SElement can have two different kinds of children: another SElement or a ContentItem (which can be marked content (MC), or a PDF object reference (OBJR)).

static Create(doc, struct_type)

Creates a new SElement.

Parameters:

• doc (PDFDoc) –

• struct_type (string) –

CreateContentItem(doc, page, insert_before=-1)

Parameters:

• doc (PDFDoc) – The document in which the new ContentItem will be created in.

• page (Page) – The page object to insert the ContentItem in.

• insert_before (int) – The position after which the kid is inserted. If element currently has no kids, insert_before is ignored.

GetActualText()

Return type:

string

Returns:

The ActualText associated with this element.

Notes: The ActualText can be defined as an empty string. To differentiate between an ActualText string of zero length and no ActualText being defined, use HasActualText().

GetAlt()

Return type:

string

Returns:

The alternate text associated with this element.

Notes: The Alt text can be defined as an empty string. To differentiate between an Alt text string of zero length and no Alt text being defined, use HasAlt().

GetAsContentItem(index)

Return type:

ContentItem

Returns:

The kid at a given array index assuming that the kid is a ContentItem.

Notes: use IsContentItem(index) prior to calling this method to make sure that the kid is indeed a ContentItem.

Parameters:

index (int) – The index of the kid to obtain.

GetAsStructElem(index)

Return type:

SElement

Returns:

The kid at a given array index assuming that the kid is a SElement.

Notes: use IsContentItem(index) prior to calling this method to make sure that the kid is not a ContentItem and is another SElement.

Parameters:

index (int) – The index of the kid to obtain.

GetID()

Return type:

Obj

Returns:

the ID of an element, or NULL if the ID is not defined.

GetNumKids()

Return type:

int

Returns:

The number of direct kids.

GetParent()

Return type:

SElement

Returns:

The immediate ancestor element of the specified element in the structure tree.

Notes: If the element’s parent is the structure tree root, the returned SElement will be not valid (i.e. element.IsValid() -> false) and the underlying SDF/Cos object will be NULL.

GetSDFObj()

Return type:

Obj

Returns:

Pointer to the underlying SDF/Cos object.

GetStructTreeRoot()

Return type:

STree

Returns:

The structure tree root of the document that directly or indirectly contains this element.

GetTitle()

Return type:

string

Returns:

The title of this structure element.

GetType()

Return type:

string

Returns:

The element’s structural element type. The type corresponds to the ‘S’ (i.e. subtype) key in the structure element dictionary.

The type identifies the nature of the structure element and its role within the document (such as a chapter, paragraph, or footnote).

HasActualText()

Return type:

boolean

Returns:

if this structure element defines ActualText.

ActualText is an exact replacement for the structure element and its children. This replacement text is useful when extracting the document’s contents in support of accessibility to users with disabilities or for other purposes.

HasAlt()

Return type:

boolean

Returns:

if this structure element defines Alt text.

Alt text is an alternate description of the structure element and its children in human-readable form, which is useful when extracting the document’s contents in support of accessibility.

HasTitle()

Return type:

boolean

Returns:

if this SElement has title.

The title of the structure element, a text string representing it in human-readable form.

Insert(kid, insert_before)

Inserts the specified kid SElement into this element.

Parameters:

insert_before (int) – The position after which the kid is inserted. If element currently has no kids, insert_before is ignored.

IsContentItem(index)

Return type:

boolean

Returns:

true if the kid at a given array index is a content item, false otherwise.

Parameters:

index (int) – The index of the kid type to obtain.

To retrieve a content item at a given array index use GetAsContentItem(index), otherwise use GetAsStructElem(index)

IsValid()

Return type:

boolean

Returns:

true if this is a valid structure element object, false otherwise.

property mp_elem

property thisown

The membership flag

apryse_sdk.SElement_Create(doc, struct_type)

Creates a new SElement.

Parameters:

• doc (PDFDoc) –

• struct_type (string) –

class apryse_sdk.STree(args)

Bases: object

STree is the root of the structure tree, which is a central repository for information related to a PDF document’s logical structure. There is at most one structure tree in each document.

static Create(doc)

Create a structure tree if it is missing, else return the existing structure tree

Parameters:

doc (PDFDoc) – the document in which to create or get the structure tree from

Return type:

STree

Returns:

structure tree of the document

GetClassMap()

Return type:

ClassMap

Returns:

the ClassMap object from the structure tree root.

GetElement(id_buf, id_buf_sz)

Return type:

SElement

Returns:

the element associated with the given ID.

Parameters:

• id_buf (string) – A pointer to a buffer containing the ID to search for.

• id_buf_sz (int) – The number of characters in id_buf.

GetKid(index)

Return type:

SElement

Returns:

The kid at an array index in the structure tree root.

Parameters:

index (int) – The index of the kid to obtain.

GetNumKids()

Return type:

int

Returns:

The number of kids of the structure tree root.

GetRoleMap()

Return type:

RoleMap

Returns:

the RoleMap object from the structure tree root.

GetSDFObj()

Return type:

Obj

Returns:

Pointer to the underlying SDF/Cos object.

Insert(kid, insert_before)

Inserts the specified kid element after the given position as a kid of the specified structure tree root.

Parameters:

• kid (SElement) – The kid element to insert.

• insert_before (int) – The position after which the kid is inserted. If element currently has no kids, insert_before is ignored.

IsValid()

Return type:

boolean

Returns:

true if this is a valid STree object, false otherwise.

property thisown

The membership flag

apryse_sdk.STree_Create(doc)

Create a structure tree if it is missing, else return the existing structure tree

Parameters:

doc (PDFDoc) – the document in which to create or get the structure tree from

Return type:

STree

Returns:

structure tree of the document

class apryse_sdk.SVGConvertOptions

Bases: object

GetConvertLinks()

Gets the value ConvertLinks from the options object Instructs the conversion process to generate interactive Link annotations from links in the SVG input file.

Return type:

boolean

Returns:

a bool, the current value for ConvertLinks.

GetDefaultFontFamily()

Gets the value DefaultFontFamily from the options object Name of the font family which is used if a font for some text in the graphics file is either not specified or not available. Default: Arial Unicode MS if available, otherwise Helvetica.

Return type:

string

Returns:

a string, the current value for DefaultFontFamily.

GetFallbackFontFamily()

Gets the value FallbackFontFamily from the options object Name of the font family which is used to create a fallback font for each font, in addition to the fallback fonts which may have been specified in the graphics file. Default: empty.

Return type:

string

Returns:

a string, the current value for FallbackFontFamily.

GetFallbackHeight()

Gets the value FallbackHeight from the options object Affects only SVG graphics without absolute size; ignored if ForcedHeight is supplied. Height >= 0 of the SVG graphics for the fitting process. If the value is zero the bounding box is calculated. Default: values in the SVG graphics if present, otherwise 0.

Return type:

double

Returns:

a double, the current value for FallbackHeight.

GetFallbackWidth()

Gets the value FallbackWidth from the options object Affects only SVG graphics without absolute size; ignored if ForcedWidth is supplied. Width >= 0 of the SVG graphics for the fitting process. If the value is zero the bounding box is calculated. Default: values in the SVG graphics if present, otherwise 0.

Return type:

double

Returns:

a double, the current value for FallbackWidth.

GetForceSRGB()

Gets the value ForceSRGB from the options object If true, all non-sRGB color specifications are ignored and the sRGB fallback color is used instead. This option does not affect referenced images. Default: false.

Return type:

boolean

Returns:

a bool, the current value for ForceSRGB.

GetForcedHeight()

Gets the value ForcedHeight from the options object The height of the SVG graphics is ignored and the specified value is applied instead if a value >= 1 is supplied. Default: height attribute of the graphics.

Return type:

double

Returns:

a double, the current value for ForcedHeight.

GetForcedWidth()

Gets the value ForcedWidth from the options object The width of the SVG graphics is ignored and the specified value is applied instead if a value >= 1 is supplied. Default: width attribute of the graphics.

Return type:

double

Returns:

a double, the current value for ForcedWidth.

GetHonorIccProfile()

Gets the value HonorIccProfile from the options object If true, honor all ICC profiles in icc-color specifications or implicitly in sRGB colors; otherwise all explicit ICC colors and implicit sRGB colors are interpreted as device-gray/device-rgb/device-cmyk colors. Default: true.

Return type:

boolean

Returns:

a bool, the current value for HonorIccProfile.

GetInline()

Gets the value Inline from the options object If true, create output inline in the content stream; otherwise a separate Form XObject is created. The inline method suffers from disadvantages related to transparency handling. On the other hand, this option is required if active links in the graphics should be converted (option ConvertLinks). Default: true.

Return type:

boolean

Returns:

a bool, the current value for Inline.

GetInternalObj(args)

GetLang()

Gets the value Lang from the options object Natural language for the graphics file as a BCP 47 language tag consisting of a two- or three-character language code according to ISO 639-1/2 which can be used e.g. in an SVG switch element. Default: the language identifier found in the LANG environment variable.

Return type:

string

Returns:

a string, the current value for Lang.

SetConvertLinks(value)

Sets the value for ConvertLinks in the options object Instructs the conversion process to generate interactive Link annotations from links in the SVG input file.

Parameters:

value: – the new value for ConvertLinks

Return type:

SVGConvertOptions

Returns:

this object, for call chaining

SetDefaultFontFamily(value)

Sets the value for DefaultFontFamily in the options object Name of the font family which is used if a font for some text in the graphics file is either not specified or not available. Default: Arial Unicode MS if available, otherwise Helvetica.

Parameters:

value: – the new value for DefaultFontFamily

Return type:

SVGConvertOptions

Returns:

this object, for call chaining

SetFallbackFontFamily(value)

Sets the value for FallbackFontFamily in the options object Name of the font family which is used to create a fallback font for each font, in addition to the fallback fonts which may have been specified in the graphics file. Default: empty.

Parameters:

value: – the new value for FallbackFontFamily

Return type:

SVGConvertOptions

Returns:

this object, for call chaining

SetFallbackHeight(value)

Sets the value for FallbackHeight in the options object Affects only SVG graphics without absolute size; ignored if ForcedHeight is supplied. Height >= 0 of the SVG graphics for the fitting process. If the value is zero the bounding box is calculated. Default: values in the SVG graphics if present, otherwise 0.

Parameters:

value: – the new value for FallbackHeight

Return type:

SVGConvertOptions

Returns:

this object, for call chaining

SetFallbackWidth(value)

Sets the value for FallbackWidth in the options object Affects only SVG graphics without absolute size; ignored if ForcedWidth is supplied. Width >= 0 of the SVG graphics for the fitting process. If the value is zero the bounding box is calculated. Default: values in the SVG graphics if present, otherwise 0.

Parameters:

value: – the new value for FallbackWidth

Return type:

SVGConvertOptions

Returns:

this object, for call chaining

SetForceSRGB(value)

Sets the value for ForceSRGB in the options object If true, all non-sRGB color specifications are ignored and the sRGB fallback color is used instead. This option does not affect referenced images. Default: false.

Parameters:

value: – the new value for ForceSRGB

Return type:

SVGConvertOptions

Returns:

this object, for call chaining

SetForcedHeight(value)

Sets the value for ForcedHeight in the options object The height of the SVG graphics is ignored and the specified value is applied instead if a value >= 1 is supplied. Default: height attribute of the graphics.

Parameters:

value: – the new value for ForcedHeight

Return type:

SVGConvertOptions

Returns:

this object, for call chaining

SetForcedWidth(value)

Sets the value for ForcedWidth in the options object The width of the SVG graphics is ignored and the specified value is applied instead if a value >= 1 is supplied. Default: width attribute of the graphics.

Parameters:

value: – the new value for ForcedWidth

Return type:

SVGConvertOptions

Returns:

this object, for call chaining

SetHonorIccProfile(value)

Sets the value for HonorIccProfile in the options object If true, honor all ICC profiles in icc-color specifications or implicitly in sRGB colors; otherwise all explicit ICC colors and implicit sRGB colors are interpreted as device-gray/device-rgb/device-cmyk colors. Default: true.

Parameters:

value: – the new value for HonorIccProfile

Return type:

SVGConvertOptions

Returns:

this object, for call chaining

SetInline(value)

Sets the value for Inline in the options object If true, create output inline in the content stream; otherwise a separate Form XObject is created. The inline method suffers from disadvantages related to transparency handling. On the other hand, this option is required if active links in the graphics should be converted (option ConvertLinks). Default: true.

Parameters:

value: – the new value for Inline

Return type:

SVGConvertOptions

Returns:

this object, for call chaining

SetLang(value)

Sets the value for Lang in the options object Natural language for the graphics file as a BCP 47 language tag consisting of a two- or three-character language code according to ISO 639-1/2 which can be used e.g. in an SVG switch element. Default: the language identifier found in the LANG environment variable.

Parameters:

value: – the new value for Lang

Return type:

SVGConvertOptions

Returns:

this object, for call chaining

property thisown

The membership flag

class apryse_sdk.SVGOutputOptions

Bases: object

A class containing options for ToSvg functions

SetAnnots(annots)

Control generation of form fields and annotations in SVG.

Parameters:

annots (boolean) – if false, no form fields or annotations are converted. Default is true

SetCompress(svgz)

Compress output SVG files using SVGZ.

Parameters:

svgz (boolean) – if true, SVG files are written in compressed format. Default is false.

SetCreateXmlWrapper(xml)

Create a XML document that contains metadata of the SVG document created.

Parameters:

xml (boolean) – if true, XML wrapper is created. Default is true.

SetDtd(dtd)

Set whether the DTD declaration is included in the SVG files.

Parameters:

dtd (boolean) – if false, no DTD is added to SVG files. Default is true.

SetEmbedFonts(embed_fonts)

Sets whether to embed fonts into each SVG page file, or to have them shared.

Parameters:

embed_fonts (boolean) – if true, fonts are injected into each SVG page. Otherwise they are created as separate files that are shared between SVG pages. Default is false.

SetEmbedImages(embed_images)

Sets whether to embed all images

Parameters:

embed_images (boolean) – if true, images will be embedded. Default is false.

SetFlattenContent(flatten)

Flatten images and paths into a single background image overlaid with vector text. This option can be used to improve speed on devices with little processing power such as iPads. Default is e_fast.

Parameters:

flatten (int) – select which flattening mode to use.

SetFlattenDPI(dpi)

The output resolution, from 1 to 1000, in Dots Per Inch (DPI) at which to render elements which cannot be directly converted. Default is 140.

Parameters:

dpi (int) – the resolution in Dots Per Inch

SetFlattenMaximumImagePixels(max_pixels)

Specifies the maximum image slice size in pixels. Default is 2000000. Notes: This setting now will no longer reduce the total number of image pixels. Instead a lower value will just produce more slices and vice versa. Since image compression works better with more pixels a larger max pixels should generally create smaller files.

Parameters:

max_pixels (int) – the maximum number of pixels an image can have

SetFlattenThreshold(threshold)

Used to control how precise or relaxed text flattening is. When some text is preserved (not flattened to image) the visual appearance of the document may be altered.

Parameters:

threshold (int) – the threshold setting to use.

SetIndividualCharPlacement(individual_char_placement)

Some viewers do not support the default text positioning correctly. This option works around this issue to place text correctly, but produces verbose output. This option will override SetRemoveCharPlacement

Parameters:

individual_char_placement (boolean) – if true, text will be positioned correctly

SetNoFonts(no_fonts)

Sets whether to disable conversion of font data to SVG

Parameters:

no_fonts (boolean) – if true, font data conversion is disabled. Default is false.

SetNoUnicode(no_unicode)

Sets whether to disable mapping of text to public Unicode region. Instead text will be converted using a custom encoding

Parameters:

no_unicode (boolean) – if true, mapping of text to public Unicode region is disabled

SetOutputThumbnails(include_thumbs)

Sets whether per page thumbnails should be included in the file. Default is true.

Parameters:

include_thumbs (boolean) – if true thumbnails will be included

SetOverprint(mode)

Enable or disable support for overprint and overprint simulation. Overprint is a device dependent feature and the results will vary depending on the output color space and supported colorants (i.e. CMYK, CMYK+spot, RGB, etc). Default is e_op_pdfx_on.

Parameters:

op – e_op_on: always enabled; e_op_off: always disabled; e_op_pdfx_on: enabled for PDF/X files only.

SetRemoveCharPlacement(remove_char_placement)

Sets whether to disable the output of character positions. This will produce slightly smaller output files than the default setting, but many viewers do not support the output correctly

Parameters:

remove_char_placement (boolean) – if true, the output of character positions is disabled

SetSvgFonts(svg_fonts)

Sets whether to convert all fonts to SVG or not.

Parameters:

svg_fonts (boolean) – if true, fonts are converted to SVG. Otherwise they are converted to OpenType. Default is false.

SetThumbnailSize(size)

The maximum dimension for thumbnails.

Parameters:

size (int) – the maximum dimension (width or height) that thumbnails will have. Default is 400.

property thisown

The membership flag

class apryse_sdk.Screen(args)

Bases: Annot

A screen annotation (PDF 1.5) specifies a region of a page upon which media clips may be played. It also serves as an object from which actions can be triggered.

static Create(doc, pos)

Creates a new Screen annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds in default user space units.

Return type:

Screen

Returns:

A newly created blank Screen annotation.

static CreateAnnot(doc, pos)

GetAction()

Returns the action of the Screen annotation

Return type:

Action

Returns:

An action object representing the action of the annotation.

Notes: The action is an action that shall be performed when the annotation is activated.

GetBackgroundColor()

Returns the background color of the annotation.

Return type:

ColorPt

Returns:

A color object that denotes the color of the Screen background.

Notes: The color can be in different color spaces: Gray, RGB, or CMYK. Call “GetBackgroundColorCompNum” to access the color space information corresponding to the border color.

GetBackgroundColorCompNum()

Returns the number indicating background color space of the annotation.

Return type:

int

Returns:

An integer indicating a color space value from the ColorSpace::Type enum. That is, 1 corresponding to “e_device_gray”, 3 corresponding to “e_device_rgb”, and 4 corresponding to “e_device_cmyk” if color space is applicable, 0 means no background color was assigned.

GetBorderColor()

Returns the border color of the annotation.

Return type:

ColorPt

Returns:

A color object that denotes the color of the Screen border.

Notes: The color can be in different color spaces: Gray, RGB, or CMYK. Call “GetBorderColorCompNum” to access the color space information corresponding to the border color.

GetBorderColorCompNum()

Returns the number indicating border color space of the annotation.

Return type:

int

Returns:

An integer indicating a color space value from the ColorSpace::Type enum. That is, 1 corresponding to “e_device_gray”, 3 corresponding to “e_device_rgb”, and 4 corresponding to “e_device_cmyk”. 0 means this annotation had no color assigned.

GetFitFull()

Returns the “fit full” flag.

Return type:

boolean

Returns:

A boolean value indicating the “fit full” flag value.

Notes: the fit full flag, if true, indicates that the button appearance shall be scaled to fit fully within the bounds of the annotation without taking into consideration the line width of the border. Default value: false.

GetHIconLeftOver()

Returns the horizontal leftover space of the icon within the annotation.

Return type:

double

Returns:

A number indicating the horizontal leftover space of the icon within the annotation.

Notes: the horizontal leftover is a number that shall be between 0.0 and 1.0 indicating the fraction of leftover space to allocate at the left. A value of 0.0 shall position the icon at the left of the annotation rectangle. A value of 0.5 shall center it in the horizontal direction within the rectangle. This entry shall be used only if the icon is scaled proportionally. Default value: 0.5.

GetIconCaptionRelation()

Returns the Icon and caption relationship of the annotation.

Return type:

int

Returns:

A value of the “IconCaptionRelation” enum type. Default value: e_NoIcon.

See also: IconCaptionRelation

GetMouseDownCaptionText()

Returns the button down caption text of the annotation.

Return type:

string

Returns:

A string containing the button down text of the annotation.

Notes: The button down caption shall be displayed when the mouse button is pressed within its active area.

GetMouseDownIcon()

Returns the Mouse Down icon associated with the annotation.

Return type:

Obj

Returns:

An SDF object that represents the Mouse Down icon associated with the annotation.

Notes: The Mouse Down icon object is a form XObject defining the annotation’s alternate (down) icon, which shall be displayed when the mouse button is pressed within its active area.

GetRolloverCaptionText()

Returns the rollover caption text of the annotation.

Return type:

string

Returns:

A string containing the rollover caption text of the annotation.

Notes: The rollover caption shall be displayed when the user rolls the cursor into its active area without pressing the mouse button.

GetRolloverIcon()

Returns the rollover icon associated with the annotation.

Return type:

Obj

Returns:

An SDF object that represents the rollover icon associated with the annotation.

Notes: The rollover icon object is a form XObject defining the annotation’s rollover icon, which shall be displayed when the user rolls the cursor into its active area without pressing the mouse button.

GetScaleCondition()

Returns the condition under which the icon should be scaled.

Return type:

int

Returns:

A value of the “ScaleCondition” enum type. Default value: e_Always.

See also: ScaleCondition

GetScaleType()

Returns the Scale Type of the annotation.

Return type:

int

Returns:

A value of the “ScaleType” enum which represents the Scale Type of the annotation. Default value: P.

See also: ScaleType

GetStaticCaptionText()

Returns static caption text of the annotation.

Return type:

string

Returns:

A string containing the static caption text of the annotation.

Notes: The static caption is the annotation’s normal caption, which shall be displayed when it is not interacting with the user.

GetStaticIcon()

Returns the static icon associated with the annotation.

Return type:

Obj

Returns:

An SDF object that represents the static icon associated with the annotation.

Notes: The static icon object is a form XObject defining the annotation’s normal icon, which shall be displayed when it is not interacting with the user.

GetTitle()

Returns the title of the annotation.

Return type:

string

Returns:

A string representing the title of the annotation.

GetVIconLeftOver()

Returns the vertical leftover space of the icon within the annotation.

Return type:

double

Returns:

a number indicating the vertical leftover space of the icon within the annotation.

Notes: the vertical leftover space is a number that shall be between 0.0 and 1.0 indicating the fraction of leftover space to allocate at the bottom of the icon. A value of 0.0 shall position the icon at the bottom of the annotation rectangle. A value of 0.5 shall center it in the vertical direction within the rectangle. This entry shall be used only if the icon is scaled proportionally. Default value: 0.5.

SetAction(action)

Sets the action of the Screen annotation (Optional; PDF 1.1 )

Parameters:

action (Action) – An action object representing the action of the annotation.

Notes: The action is an action that shall be performed when the annotation is activated.

SetBackgroundColor(col, numcomp)

Sets the background color of the annotation. (Optional)

Parameters:

• col (ColorPt) – A color point that denotes the color of the screen background.

• numcomp (int) – An integer which value indicates the color space used for the parameter c.

SetBorderColor(col, numcomp)

Sets the border color of the annotation. (Optional)

Parameters:

• col (ColorPt) – A color object that denotes the color of the screen border.

• numcomp (int) – An integer which value indicates the color space used for the parameter c.

SetFitFull(ff)

Sets the “fit full” flag. (Optional)

Parameters:

ff (boolean) – A boolean value indicating the “fit full” flag value.

Notes: the fit full flag, if true, indicates that the button appearance shall be scaled to fit fully within the bounds of the annotation without taking into consideration the line width of the border. Default value: false.

SetHIconLeftOver(hl)

Sets the horizontal leftover space of the icon within the annotation. (Optional)

Parameters:

hl (double) – A number indicating the horizontal leftover space of the icon within the annotation.

Notes: the horizontal leftover space is a number that shall be between 0.0 and 1.0 indicating the fraction of leftover space to allocate at the left. A value of 0.0 shall position the icon at the left of the annotation rectangle. A value of 0.5 shall center it in the horizontal direction within the rectangle. This entry shall be used only if the icon is scaled proportionally. Default value: 0.5.

SetIconCaptionRelation(icr)

Sets the Icon and caption relationship of the annotation. (Optional; pushbutton fields only)

Parameters:

icr (int) – A value of the “IconCaptionRelation” enum type. Default value: e_NoIcon.

See also: IconCaptionRelation

SetMouseDownCaptionText(contents)

Sets the button down caption text of the annotation. (Optional; button fields only)

Parameters:

contents (string) – A string containing the button down text of the annotation.

Notes: The button down caption shall be displayed when the mouse button is pressed within its active area.

SetMouseDownIcon(icon)

Sets the Mouse Down icon associated with the annotation. (Optional; button fields only)

Parameters:

icon (Obj) – An SDF object that represents the Mouse Down icon associated with the annotation.

Notes: The Mouse Down icon object is a form XObject defining the annotation’s alternate (down) icon, which shall be displayed when the mouse button is pressed within its active area.

SetRolloverCaptionText(contents)

Sets the roll over caption text of the annotation. (Optional; button fields only)

Parameters:

contents (string) – A string containing the roll over caption text of the annotation.

Notes: The rollover caption shall be displayed when the user rolls the cursor into its active area without pressing the mouse button.

SetRolloverIcon(icon)

Sets the rollover icon associated with the annotation. (Optional; button fields only)

Parameters:

icon (Obj) – An SDF object that represents the rollover icon associated with the annotation.

Notes: The rollover icon object is a form XObject defining the annotation’s rollover icon, which shall be displayed when the user rolls the cursor into its active area without pressing the mouse button.

SetScaleCondition(sc)

Sets the condition under which the icon should be scaled. (Optional)

Parameters:

sc (int) – A value of the “ScaleCondition” enum type. Default value: e_Always.

SetScaleType(st)

Sets the Scale Type of the annotation. (Optional)

Parameters:

st (int) – An entry of the “ScaleType” enum which represents the Scale Type of the annotation. Default value: P.

See also: ScaleType

SetStaticCaptionText(contents)

Sets static caption text of the annotation. (Optional; button fields only)

Parameters:

contents (string) – A string containing the static caption text of the annotation.

Notes: The static caption is the annotation’s normal caption, which shall be displayed when it is not interacting with the user.

SetStaticIcon(icon)

Sets the static icon associated with the annotation. (Optional; button fields only)

Parameters:

icon (Obj) – An SDF object that represents the static icon associated with the annotation.

Notes: The static icon object is a form XObject defining the annotation’s normal icon, which shall be displayed when it is not interacting with the user.

SetTitle(title)

Sets the title of the Annotation. (Optional)

Parameters:

title (string) – A string representing the title of the annotation.

SetVIconLeftOver(vl)

Sets the vertical leftover space of the icon within the annotation. (Optional)

Parameters:

vl (double) – A number indicating the vertical leftover space of the icon within the annotation.

Notes: the vertical leftover space is a number that shall be between 0.0 and 1.0 indicating the fraction of leftover space to allocate at the bottom of the icon. A value of 0.0 shall position the icon at the bottom of the annotation rectangle. A value of 0.5 shall center it in the vertical direction within the rectangle. This entry shall be used only if the icon is scaled proportionally. Default value: 0.5.

e_Always = 0

Always scale

e_Anamorphic = 0

e_CAboveI = 3

e_CBelowI = 2

e_CLeftIRight = 5

e_COverlayI = 6

e_CRightILeft = 4

e_Never = 3

Never scale

e_NoCaption = 1

e_NoIcon = 0

e_Proportional = 1

e_WhenBigger = 1

Scale only when the icon is bigger than the annotation rectangle

e_WhenSmaller = 2

Scale only when the icon is smaller than the annotation rectangle

property thisown

The membership flag

apryse_sdk.Screen_Create(doc, pos)

Creates a new Screen annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds in default user space units.

Return type:

Screen

Returns:

A newly created blank Screen annotation.

apryse_sdk.Screen_CreateAnnot(doc, pos)

class apryse_sdk.SearchResult(args)

Bases: object

The result of running PDF::TextSearch::Run()

GetAmbientString()

Return type:

string

Returns:

the ambient string of the found string (computed only if ‘e_ambient_string’ is set).

GetHighlights()

Return type:

Highlights

Returns:

The Highlights info associated with the match (computed only if ‘e_highlight’ is set).

GetMatch()

Return type:

string

Returns:

the string that matches the search pattern.

GetPageNumber()

Return type:

int

Returns:

the number of the page with the match.

IsDocEnd()

Return type:

boolean

Returns:

true if finished searching the entire document.

IsFound()

Return type:

boolean

Returns:

true if a match was found.

IsPageEnd()

Return type:

boolean

Returns:

true if finished searching a page.

property thisown

The membership flag

class apryse_sdk.SecurityHandler(args)

Bases: object

Standard Security Handler is a standard password-based security handler.

Authorize(p)

The method is called when a user tries to set security for an encrypted document and when a user tries to open a file. It must decide, based on the contents of the authorization data structure, whether or not the user is permitted to open the file, and what permissions the user has for this file.

Notes: - This callback must not obtain the authorization data (e.g. by displaying a user interface into which a user can type a password). This is handled by the security handler’s GetAuthorizationData(), which must be called before this callback. Instead, Authorize() should work with authorization data it has access to.

Parameters:

p (int) –

• permission to authorize

AuthorizeFailed()

A callback method indicating repeated failed authorization. Override this callback in order to provide a UI feedback for failed authorization. Default implementation returns immediately.

ChangeMasterPassword(args)

Overload 1:

Set the new master password to a binary string

Parameters:

password (string) – the new user password

Remarks: Deprecated. Use versions that accepts UString or buffer instead.

Overload 2:

Sets the new master/owner password.

Parameters:

password (string) – The new master/owner password.

Overload 3:

Sets the new master/owner password.

Parameters:

password_buf (std::vector< int,std::allocator< int > >) – The new master/owner password.

ChangeMasterPasswordASCII(password)

Set the new master password to an ASCII text string

Parameters:

password (string) – the new master/owner password

Remarks: Deprecated. Use versions that accepts UString or buffer instead.

ChangeRevisionNumber(rev_num)

Change the revision number and the encryption algorithm of the standard security handler.

Parameters:

rev_num (int) –

the new revision number of the standard security algorithm. Currently allowed values for the revision number are (see Table 3.18 in PDF Reference Manual v1.6 for more details):

• 2 : Encryption using 40-bit RC4 algorithm.

• 3 : Encryption using 128-bit RC4 algorithm. Available in PDF 1.4 and above.

• 4Encryption using Crypt filters and 128-bit AES (Advanced Encryption

  Standard) algorithm. Available in PDF 1.6 and above.

ChangeUserPassword(args)

Overload 1:

Set the new user password to a binary string

Parameters:

password (string) – the new user password

Remarks: Deprecated. Use versions that accepts UString or buffer instead.

Overload 2:

Sets the new user password.

Parameters:

password (string) – The new user password.

Overload 3:

Sets the new user password.

Parameters:

password_buf (std::vector< int,std::allocator< int > >) – The new user password.

ChangeUserPasswordASCII(password)

Set the new user password to an ASCII text string

Parameters:

password (string) – the new user password

Remarks: Deprecated. Use versions that accepts UString or buffer instead..

Clone(base)

Return type:

SecurityHandler

Returns:

A new, cloned instance of SecurityHandler.

Notes: this method must be implemented in any derived class from SecurityHandler.

EditSecurityData(doc)

Called when the security handler should activate a dialog box with the current security settings that may be modified.

Return type:

boolean

Returns:

true if the operation was successful false otherwise.

FillEncryptDict(doc)

Called when an encrypted document is saved. Fills the document’s Encryption dictionary with whatever information the security handler wants to store in the document.

The sequence of events during creation of the encrypt_dict is as follows:

• encrypt_dict is created (if it does not exist)

• Filter attribute is added to the dictionary

• call this method to allow the security handler to add its own attributes

• call the GetCryptKey to get the algorithm version, key, and key length

• checks if the V attribute has been added to the dictionary and, if not, then sets V to the algorithm version

• set the Length attribute if V is 2 or greater

• add the encrypt_dict to the document

  type doc:

  SDFDoc

Parameters:

doc –

• The document to save.

rtype:

Obj

return:

• encrypt_dict

Warning: - Unlike all other strings and streams, direct object elements of the encrypt_dict are not encrypted automatically. If you want them encrypted, you must encrypt them before inserting them into the dictionary.

GetAuthorizationData(req_opr)

This method is invoked in case Authorize() failed. The callback must determine the user’s authorization properties for the document by obtaining authorization data (e.g. a password through a GUI dialog).

The authorization data is subsequently used by the security handler’s Authorize() to determine whether or not the user is authorized to open the file.

Return type:

boolean

Returns:

false if the operation was canceled, true otherwise.

Parameters:

req_opr (int) –

• the permission for which authorization data is requested.

GetDerived()

Return type:

SecurityHandler

Returns:

The derived class or NULL for standard security handler.

GetEncryptionAlgorithmID()

Return type:

int

Returns:

The encryption algorithm identifier. A code specifying the algorithm to be used in encrypting and decrypting the document. Returned number corresponds to V entry in encryption dictionary. Currently allowed values are from 0-4. See PDF Reference Manual for more details.

GetHandlerDocName()

Return type:

string

Returns:

The name of the security handler as it appears in the serialized file as the value of /Filter key in /Encrypt dictionary.

GetKeyLength()

Return type:

int

Returns:

The length of the encryption key in bytes.

Notes: The returned key length is given in bytes.

GetMasterPassword()

Return type:

string

Returns:

Current master (owner) password.

GetMasterPasswordSize()

Return type:

int

Returns:

Length of the current owner password string. This has to be used when password is a non-ASCII string that may contain ‘’ bytes.

GetPermission(p)

Return type:

boolean

Returns:

true if the SecurityHandler permits the specified action (Permission p) on the document, or false if the permission was not granted.

Parameters:

p (int) – A Permission to be granted.

Notes: in order to check for permission the method will repeatedly (up to three times) attempt to GetAuthorizationData() and Authorize() permission. If the permission is not granted AuthorizeFailed() callback will be called. This callback method allows derived class to provide UI feedback for failed authorization.

GetRevisionNumber()

Return type:

int

Returns:

the revision number of the standard security algorithm.

GetUserPassword()

Return type:

string

Returns:

Current user password.

GetUserPasswordSize()

Return type:

int

Returns:

Length of the current user password string. This has to be used when password is a non-ASCII string that may contain ‘’ bytes.

InitPassword(args)

Overload 1:

The method can be called in GetAuthorizationData() callback to specify user supplied non-ASCII password.

Remarks: Deprecated. Use versions that accepts UString or buffer instead.

Overload 2:

This method can be called in GetAuthorizationData() callback to specify user supplied password.

Overload 3:

This method can be called in GetAuthorizationData() callback to specify user supplied password.

InitPasswordASCII(password)

The method can be called in GetAuthorizationData() callback to specify user supplied ASCII password.

Remarks: Deprecated. Use versions that accepts UString or buffer instead.

IsAES(args)

Overload 1:

Return type:

boolean

Returns:

true is this security handler uses 128 bit AES (Advanced Encryption Standard) algorithm to encrypt strings or streams.

Overload 2:

The following function can be used to verify whether a given stream is encrypted using AES.

Return type:

boolean

Returns:

true if the given stream is encrypted using AES encryption.

Parameters:

stream (Obj) – A pointer to an SDF::Stream object

IsMasterPasswordRequired()

Return type:

boolean

Returns:

true if the SecurityHandler requires a master (owner) password.

IsModified()

Return type:

boolean

Returns:

• true if the SecurityHandler was modified (by calling SetModified())

or false otherwise.

If the user changes SecurityHandler’s settings (e.g. by changing a password), IsModified() should return true.

IsRC4()

Return type:

boolean

Returns:

true is this security handler uses RC4 algorithm to encrypt strings or streams.

IsUserPasswordRequired()

Return type:

boolean

Returns:

true if the SecurityHandler requires a user password.

IsValid()

Return type:

boolean

Returns:

• true if the SecurityHandler is valid.

SetDerived(overloaded_funct)

This method informs base security handler which methods are overridden in the derived class. The only place this method needs to be invoked is in Create(name, key_len, enc_code) static factory method in the derived class.

Parameters:

overloaded_funct (int) – A flag that specifies which functions are overloaded in the derived class. For example: SetDerived(SecurityHandler::has_Clone + SecurityHandler::has_FillEncDictProc);

SetEncryptMetadata(encrypt_metadata)

Indicates whether the document-level metadata stream is to be encrypted.

Parameters:

encrypt_metadata (boolean) – true if metadata stream should be encrypted, false otherwise.

Notes: EncryptMetadata flag affects only Crypt filters available in PDF 1.5 (Acrobat 6) and later. By default, metadata stream will be encrypted.

SetModified(is_modified=True)

The method allows derived classes to set SecurityHandler is modified flag. This method should be called whenever there are changes (e.g. a password change) to the SecurityHandler

Parameters:

is_modified (boolean) – Value to set the SecurityHandler’s is modified flag to

SetPermission(perm, value)

Set the permission setting of the StdSecurityHandler.

Parameters:

• perm (int) –

  indicates a permission to set or clear. It can be any of the following values:

  e_print // print the document. e_doc_modify // edit the document more than adding or modifying text notes. e_extract_content // enable content extraction e_mod_annot // allow modifications to annotations e_fill_forms // allow changes to fill in forms e_access_support // content access for the visually impaired. e_assemble_doc // allow document assembly e_print_high // high resolution print.

• value (boolean) – true if the permission/s should be granted, false otherwise.

e_AES = 3

Use Crypt filters with 128-bit AES (Advanced Encryption Standard) algorithm.

e_AES_256 = 4

Use Crypt filters with 256-bit AES (Advanced Encryption Standard) algorithm.

e_RC4_128 = 2

128-bit RC4 algorithm.

e_RC4_40 = 1

40-bit RC4 algorithm.

e_access_support = 9

content access for the visually impaired.

e_assemble_doc = 10

allow document assembly

e_doc_modify = 3

edit the document more than adding or modifying text notes.

e_doc_open = 2

open and decrypt the document.

e_extract_content = 6

enable content extraction

e_fill_forms = 8

allow changes to fill in forms

e_mod_annot = 7

allow modifications to annotations

e_owner = 1

the user has ‘owner’ rights (e.g. rights to change the document’s security settings).

e_print = 4

print the document.

e_print_high = 5

high resolution print.

has_AuthFailedProc = 4

has_AuthProc = 2

has_CloneProc = 1

has_EditSecurDataProc = 16

has_FillEncDictProc = 32

has_GetAuthDataProc = 8

property m_derived_procs

property m_owner

property mp_handler

property thisown

The membership flag

class apryse_sdk.Selection(args)

Bases: object

A class representing the current text selection.

GetAsHtml()

Return type:

string

Returns:

the current text selection in HTML format. HTML text will contain styling information such as text color, font size, style etc.

Notes: this function can be used to implement clipboard copy and paste that preserves text formating.

GetAsUnicode()

Return type:

string

Returns:

the current text selection represented as an Unicode string.

GetPageNum()

Return type:

int

Returns:

the page number containing the selected text.

GetQuads()

Returns the list of tight bounding quads in the current text selection. :param quads: - Sets a pointer to an array of vertices representing

a list of bounding quads for the selected text. Each bounding quad is represented using 8 numbers in an array of doubles. Each two consecutive values represent the x and y coordinates of a quad vertex and the four vertices are arranged counter-clockwisely,

3——–2 | | | | | | 0——–1

e.g., (quad[0], quad[1]) is the coordinate of vertex 0, and (quad[4], quad[5]) is the coordinate of vertex 2. Note that it is only ensured that the four vertices are arranged sequentially; it is possible in practice that (quad[0], quad[1]) is the coordinate of any vertex.

Return type:

std::vector< QuadPoint,std::allocator< PDF::QuadPoint > >

Returns:

the number of quads in ‘quads’ array.

Notes: the ‘quads’ array is owned by the current selection and does not need to be explicitly released.

property thisown

The membership flag

class apryse_sdk.Separation(args)

Bases: object

This class is used to store separations in PDFRasterize and PDFDraw

C()

GetData()

GetDataSize()

GetSeparationName()

K()

M()

Y()

property m_separation_name

property thisown

The membership flag

class apryse_sdk.Shading(args)

Bases: object

Shading is a class that represents a flat interface around all PDF shading types:

• In Function-based (type 1) shadings, the color at every point in the domain is defined by a specified mathematical function. The function need not be smooth or continuous. This is the most general of the available shading types, and is useful for shadings that cannot be adequately described with any of the other types.

• Axial shadings (type 2) define a color blend along a line between two points, optionally extended beyond the boundary points by continuing the boundary colors.

• Radial shadings (type 3) define a color blend that varies between two circles. Shadings of this type are commonly used to depict three-dimensional spheres and cones.

• Free-form Gouraud-shaded triangle mesh shadings (type 4) and lattice Gouraud shadings (type 5) are commonly used to represent complex colored and shaded three-dimensional shapes. The area to be shaded is defined by a path composed entirely of triangles. The color at each vertex of the triangles is specified, and a technique known as Gouraud interpolation is used to color the interiors. The interpolation functions defining the shading may be linear or nonlinear.

• Coons patch mesh shadings (type 6) areructed from one or more color patches, each bounded by four cubic Bezier curves.

  A Coons patch generally has two independent aspects: - Colors are specified for each corner of the unit square, and bilinear

  interpolation is used to fill in colors over the entire unit square

  • Coordinates are mapped from the unit square into a four-sided patch whose sides are not necessarily linear. The mapping is continuous: the corners of the unit square map to corners of the patch and the sides of the unit square map to sides of the patch.

• Tensor-product patch mesh shadings (type 7) are identical to type 6 (Coons mesh), except that they are based on a bicubic tensor-product patch defined by 16 control points, instead of the 12 control points that define a Coons patch. The shading Patterns dictionaries representing the two patch types differ only in the value of the Type entry and in the number of control points specified for each patch in the data stream. Although the Coons patch is more concise and easier to use, the tensor- product patch affords greater control over color mapping.

Destroy()

Frees the native memory of the object.

GetAntialias()

Return type:

boolean

Returns:

A flag indicating whether to filter the shading function to prevent aliasing artifacts. See Table 4.25

GetBBox()

Return type:

Rect

Returns:

a rectangle giving the left, bottom, right, and top coordinates, respectively, of the shading’s bounding box. The coordinates are interpreted in the shading’s target coordinate space. If present, this bounding box is applied as a temporary clipping boundary when the shading is painted, in addition to the current clipping path and any other clipping boundaries in effect at that time.

Notes: Use HasBBox() method to determine whether the shading has a background color.

GetBackground()

An color point represented in base color space specifying a single background color value. If present, this color is used before any painting operation involving the shading, to fill those portions of the area to be painted that lie outside the bounds of the shading object itself. In the opaque imaging model, the effect is as if the painting operation were performed twice: first with the background color and then again with the shading.

Notes: The background color is applied only when the shading is used as part of a shading pattern, not when it is painted directly with the sh operator.

Use HasBackground() method to determine whether the shading has a background color.

GetBaseColorSpace()

Return type:

ColorSpace

Returns:

The color space in which color values are expressed. This may be any device, CIE-based, or special color space except a Pattern space.

GetColor(args)

Overload 1:

Return type:

ColorPt

Returns:

a color point for the given value of parametric variable t.

Notes: for shadings other than Axial or Radial this method throws an exception.

Overload 2:

Return type:

ColorPt

Returns:

a color point for the given value of parametric variable (t1, t2).

Notes: for shadings other than Function this method throws an exception.

GetCoordsAxial()

Return type:

std::vector< double,std::allocator< double > >

Returns:

for Axial shading returns four numbers (out_x0, out_y0, out_x1, out_y1) specifying the starting and ending coordinates of the axis, expressed in the shading’s target coordinate space.

Notes: for shadings other than Axial this method throws an exception.

GetCoordsRadial()

Return type:

std::vector< double,std::allocator< double > >

Returns:

for Radial shading returns six numbers (x0 y0 r0 x1 y1 r1) specifying the centers and radii of the starting and ending circles, expressed in the shading’s target coordinate space. The radii r0 and r1 must both be greater than or equal to 0. If one radius is 0, the corresponding circle is treated as a point; if both are 0, nothing is painted.

Notes: for shadings other than Radial this method throws an exception.

GetDomain()

Return type:

std::vector< double,std::allocator< double > >

Returns:

An array of four numbers [xmin xmax ymin ymax] specifying the rectangular domain of coordinates over which the color function(s) are defined. If the function does not contain /Domain entry the function returns: [0 1 0 1].

Notes: for shadings other than Function this method throws an exception.

GetMatrix()

Return type:

Matrix2D

Returns:

a matrix specifying a mapping from the coordinate space specified by the Domain entry into the shading’s target coordinate space.

Notes: for shadings other than Function this method throws an exception.

GetParamEnd()

Return type:

double

Returns:

a number specifying the limiting value of a parametric variable t. The variable is considered to vary linearly between GetParamStart() and GetParamEnd() as the color gradient varies between the starting and ending points of the axis for Axial shading or circles for Radial shading. The variable t becomes the input argument to the color function(s).

Notes: the returned value corresponds to the second value in Domain array.

for shadings other than Axial or Radial this method throws an exception.

GetParamStart()

Return type:

double

Returns:

a number specifying the limiting value of a parametric variable t. The variable is considered to vary linearly between GetParamStart() and GetParamEnd() as the color gradient varies between the starting and ending points of the axis for Axial shading or circles for Radial shading. The variable t becomes the input argument to the color function(s).

Notes: the returned value corresponds to the first value in Domain array.

for shadings other than Axial or Radial this method throws an exception.

GetSDFObj()

Return type:

Obj

Returns:

the underlying SDF/Cos object

GetType()

Return type:

int

Returns:

The shading type

HasBBox()

Return type:

boolean

Returns:

true if shading has a bounding box, false otherwise.

HasBackground()

Return type:

boolean

Returns:

true if the shading has a background color or false otherwise.

IsExtendEnd()

Return type:

boolean

Returns:

a flag specifying whether to extend the shading beyond the ending point of the axis for Axial shading or ending circle for Radial shading.

Notes: for shadings other than Axial or Radial this method throws an exception.

IsExtendStart()

Return type:

boolean

Returns:

a flag specifying whether to extend the shading beyond the starting point of the axis for Axial shading or starting circle for Radial shading.

Notes: for shadings other than Axial or Radial this method throws an exception.

e_axial_shading = 1

e_coons_shading = 5

e_free_gouraud_shading = 3

e_function_shading = 0

e_lattice_gouraud_shading = 4

e_null = 7

e_radial_shading = 2

e_tensor_shading = 6

property mp_shade

property thisown

The membership flag

class apryse_sdk.ShapedText(args)

Bases: object

The class ShapedText. A sequence of positioned glyphs – the visual representation of a given text string

Destroy()

GetFailureReason()

In the case where GetShapingStatus() returns something other than FullShaping, this method will return a more detailed reason behind the failure.

Return type:

int

Returns:

.

GetGlyph(index)

Get the glyph ID at the indicated place in the shaped sequence. This number is specific to the font file used to generate the shaping results, and does not always have a clean mapping to a particular Unicode codepoint in the original string.

Parameters:

index (int) – – the index of the glyph to be retrieved. Must be less than GetNumGlyphs().

Return type:

int

Returns:

returns the glyph ID for the indicated place in the shaped result.

GetGlyphXPos(index)

The X position of the glyph at the requested index. This number has been scaled by GetScale().

Parameters:

index (int) – – the index of the glyph position to be retrieved. Must be less than GetNumGlyphs().

Return type:

double

Returns:

returns the X position for the glyph at the specified index.

GetGlyphYPos(index)

The Y position of the glyph at the requested index. This number has been scaled by GetScale().

Parameters:

index (int) – – the index of the glyph position to be retrieved. Must be less than GetNumGlyphs().

Return type:

double

Returns:

returns the Y position for the glyph at the specified index.

GetNumGlyphs()

Number of glyphs present in the shaped text. Might be different from the .

Return type:

int

Returns:

returns the number of utf32 codepoints in this shaped text.

GetScale()

Scaling factor of this shaped text relative to the em size. A scaling factor of 1 means that all units are relative to the em size. PDF scaling is typically 1000 units per em.

Return type:

double

Returns:

returns the scaling factor for the glyph positions.

GetShapingStatus()

Get the state of the shaping operation. Even if the shaping did not fully succeed, this object can be added to an elementbuilder, and will fallback to placing unshped text. See GetFailureReason() in the case this method returns something other than FullShaping.

Return type:

int

Returns:

.

GetText()

The original source text string.

Return type:

string

Returns:

returns the source text string.

e_FontDataNotFound = 3

e_FullShaping = 0

e_NoFailure = 0

e_NoShaping = 2

e_NotIndexEncoded = 2

e_PartialShaping = 1

e_UnsupportedFontType = 1

property m_impl

property thisown

The membership flag

class apryse_sdk.SignatureHandler

Bases: object

A base class for SignatureHandler. SignatureHandler instances are responsible for defining the digest and cipher algorithms to create and/or validate a signed PDF document. SignatureHandlers are added to PDFDoc instances by calling the PDFDoc::AddSignatureHandler method.

AppendData(data)

Adds data to be signed. This data will be the raw serialized byte buffer as the PDF is being saved to any stream.

Parameters:

data (std::vector< int,std::allocator< int > >) – A chunk of data to be signed.

Clone()

This method returns a cloned copy of the current instance.

Return type:

SignatureHandler

Returns:

A new, cloned instance of SignatureHandler.

Notes: this method must be implemented in any derived class from SignatureHandler.

CreateSignature()

Calculates the actual signature using client implemented signing methods. The returned value (byte array) will be written as the /Contents entry in the signature dictionary.

Return type:

std::vector< int,std::allocator< int > >

Returns:

The calculated signature data.

GetName()

Gets the name of this SignatureHandler. The name of the SignatureHandler is what identifies this SignatureHandler from all others. This name is also added to the PDF as the value of /Filter entry in the signature dictionary.

Return type:

string

Returns:

The name of this SignatureHandler.

Reset()

Resets any data appending and signature calculations done so far. This method should allow PDFNet to restart the whole signature calculation process. It is important that when this method is invoked, any data processed with the AppendData method should be discarded.

Return type:

boolean

Returns:

True if there are no errors, otherwise false.

property thisown

The membership flag

class apryse_sdk.SignatureWidget(args)

Bases: Widget

An object representing a Signature used in a PDF Form. These Widgets can be signed directly, or signed using a DigitalSignatureField.

static Create(args)

Overload 1:

Creates a new SignatureWidget annotation in the specified document, and adds an associated signature form field to the document.

Parameters:

• doc (PDFDoc) – The document to which the widget is to be added.

• pos (Rect) – A rectangle specifying the widget’s bounds in default user space units.

• field_name (string) – The name of the digital signature field to create. Optional - autogenerated by default.

Return type:

SignatureWidget

Returns:

A newly-created blank SignatureWidget annotation.

Overload 2:

Creates a new SignatureWidget annotation associated with a particular form field in the specified document.

Parameters:

• doc (PDFDoc) – The document to which the widget is to be added.

• pos (Rect) – A rectangle specifying the widget’s bounds in default user space units.

• field (Field) – The digital signature field for which to create a signature widget.

Return type:

SignatureWidget

Returns:

A newly-created blank SignatureWidget annotation.

Overload 3:

Creates a new SignatureWidget annotation associated with a particular DigitalSignatureField object (representing a signature-type form field) in the specified document.

Parameters:

• doc (PDFDoc) – The document to which the widget is to be added.

• pos (Rect) – A rectangle specifying the widget’s bounds in default user space units.

• field (DigitalSignatureField) – The digital signature field for which to create a signature widget.

Return type:

SignatureWidget

Returns:

A newly-created blank SignatureWidget annotation.

CreateSignatureAppearance(img)

A function that will create and add an appearance to this widget by centering an image within it.

Parameters:

img (Image) – A PDF::Image object representing the image to use.

GetDigitalSignatureField()

Retrieves the DigitalSignatureField associated with this SignatureWidget.

Return type:

DigitalSignatureField

Returns:

A DigitalSignatureField object representing the digital signature form field associated with this signature widget annotation.

property thisown

The membership flag

apryse_sdk.SignatureWidget_Create(args)

Overload 1:

Creates a new SignatureWidget annotation in the specified document, and adds an associated signature form field to the document.

Parameters:

• doc (PDFDoc) – The document to which the widget is to be added.

• pos (Rect) – A rectangle specifying the widget’s bounds in default user space units.

• field_name (string) – The name of the digital signature field to create. Optional - autogenerated by default.

Return type:

SignatureWidget

Returns:

A newly-created blank SignatureWidget annotation.

Overload 2:

Creates a new SignatureWidget annotation associated with a particular form field in the specified document.

Parameters:

• doc (PDFDoc) – The document to which the widget is to be added.

• pos (Rect) – A rectangle specifying the widget’s bounds in default user space units.

• field (Field) – The digital signature field for which to create a signature widget.

Return type:

SignatureWidget

Returns:

A newly-created blank SignatureWidget annotation.

Overload 3:

Creates a new SignatureWidget annotation associated with a particular DigitalSignatureField object (representing a signature-type form field) in the specified document.

Parameters:

• doc (PDFDoc) – The document to which the widget is to be added.

• pos (Rect) – A rectangle specifying the widget’s bounds in default user space units.

• field (DigitalSignatureField) – The digital signature field for which to create a signature widget.

Return type:

SignatureWidget

Returns:

A newly-created blank SignatureWidget annotation.

class apryse_sdk.Sound(args)

Bases: Markup

A Sound annotation represents a sound recording attached to a point in the PDF document. When closed, this annotation appear as an icon; when open and activated, a sound record from the computer’s microphone or imported from a file associated with this annotation is played.The icon of this annotation by default is a speaker.

static Create(args)

Overload 1:

Creates a new Sound annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds in default user space units.

Return type:

Sound

Returns:

A newly created blank Sound annotation.

Overload 2:

Creates a new Sound annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Point) – A point specifying the annotation’s location in default user space units.

Return type:

Sound

Returns:

A newly created blank Sound annotation.

Overload 3:

Creates a new Sound annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Point) – A point specifying the annotation’s location in default user space units.

Return type:

Sound

Returns:

A newly created blank Sound annotation.

static CreateAnnot(args)

static CreateWithData(args)

Creates a new Sound annotation in the specified document. Accepts raw audio data, along with a few parameters describing the format of that data

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds in default user space units.

• source_data (Filter) – The raw sound data for the newly created annot

• bits_per_sample (int) – The number of bits per sample in source data

• sample_freq (int) – The number of samples per second present in source data

• num_channels (int) – The number of audio channels in source_data

• icon (int) – A value of the “Icon” enumeration type specifying the icon to display.

Return type:

Sound

Returns:

A newly created blank Sound annotation.

GetIcon()

Returns the Icon of the Sound annotation.

Return type:

int

Returns:

A value of the “Icon” enum. Default value: e_Speaker.

Notes: The Icon defines the appearance associated with the Sound annotation. The annotation’s appearance stream, if present, will take precedence over this entry.

GetIconName()

Returns the Icon name of the Sound annotation.

Return type:

string

Returns:

A string denoting the Icon name of the Sound annotation.

Notes: The following Icon names are equivalent to predefined Icons from the enum “Icon”: “Speaker” = e_Speaker “Mic” = e_Mic “Unknown” = e_Unknown The Icon defines the appearance associated with the Sound annotation. Names other than mentioned above do not have predefined icon appearances. The annotation’s appearance stream, if present, will take precedence over this entry.

GetSoundStream()

Returns the sound object of the Sound annotation.

Return type:

Obj

Returns:

An SDF object representing a sound stream.

Notes: The sound stream is to be played when the Sound annotation is activated.

SetIcon(args)

Overload 1:

Sets the Icon of the Sound annotation. (Optional)

Parameters:

type (int) – A value of the “Icon” enumeration type specifying the icon to display. Default value: e_Speaker.

Notes: The Icon defines the appearance associated with the Sound annotation. The annotation’s appearance stream, if present, will take precedence over this entry.

Overload 2:

Sets the Icon name of the Sound annotation. (Optional)

Parameters:

type (string) – A string denoting the Icon name of the Sound annotation.

Notes: The following Icon names are equivalent to predefined types from the enum “Icon”: “Speaker” = e_Speaker “Mic” = e_Mic “Unknown” = e_Unknown The Icon defines the appearance associated with the Sound annotation. Names other than mentioned above do not have predefined icon appearances. The annotation’s appearance stream, if present, will take precedence over this entry.

SetSoundStream(icon)

Sets the sound object of the Sound annotation.

Parameters:

icon (Obj) – An SDF object representing a sound stream.

Notes: The sound stream is to be played when the Sound annotation is activated.

e_Mic = 1

Mic sound

e_Speaker = 0

Speaker sound

e_Unknown = 2

Invalid or non-standard

property thisown

The membership flag

apryse_sdk.Sound_Create(args)

Overload 1:

Creates a new Sound annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds in default user space units.

Return type:

Sound

Returns:

A newly created blank Sound annotation.

Overload 2:

Creates a new Sound annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Point) – A point specifying the annotation’s location in default user space units.

Return type:

Sound

Returns:

A newly created blank Sound annotation.

Overload 3:

Creates a new Sound annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Point) – A point specifying the annotation’s location in default user space units.

Return type:

Sound

Returns:

A newly created blank Sound annotation.

apryse_sdk.Sound_CreateAnnot(args)

apryse_sdk.Sound_CreateWithData(args)

Creates a new Sound annotation in the specified document. Accepts raw audio data, along with a few parameters describing the format of that data

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds in default user space units.

• source_data (Filter) – The raw sound data for the newly created annot

• bits_per_sample (int) – The number of bits per sample in source data

• sample_freq (int) – The number of samples per second present in source data

• num_channels (int) – The number of audio channels in source_data

• icon (int) – A value of the “Icon” enumeration type specifying the icon to display.

Return type:

Sound

Returns:

A newly created blank Sound annotation.

class apryse_sdk.Square(args)

Bases: Markup

Square annotation is used to display a rectangle on the page. When opened, a square annotation can display a pop-up window containing the text of the associated note. The rectangle may be inscribed and possibly padded within the annotation rectangle defined by the annotation dictionary’s Rect entry.

static Create(doc, pos)

Creates a new Square annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds, in user space coordinates.

Return type:

Square

Returns:

A newly created blank Square annotation.

static CreateAnnot(doc, pos)

property thisown

The membership flag

apryse_sdk.Square_Create(doc, pos)

Creates a new Square annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds, in user space coordinates.

Return type:

Square

Returns:

A newly created blank Square annotation.

apryse_sdk.Square_CreateAnnot(doc, pos)

class apryse_sdk.Squiggly(args)

Bases: TextMarkup

A Squiggly annotation shows as a wavy line segment across the bottom of a word or a group of contiguous words.

static Create(doc, pos)

Creates a new Squiggly annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the Popup annotation is added.

• pos (Rect) – A rectangle specifying the Popup annotation’s bounds in default user space units.

Return type:

Squiggly

Returns:

A newly created blank Squiggly annotation.

static CreateAnnot(doc, pos)

property thisown

The membership flag

apryse_sdk.Squiggly_Create(doc, pos)

Creates a new Squiggly annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the Popup annotation is added.

• pos (Rect) – A rectangle specifying the Popup annotation’s bounds in default user space units.

Return type:

Squiggly

Returns:

A newly created blank Squiggly annotation.

apryse_sdk.Squiggly_CreateAnnot(doc, pos)

class apryse_sdk.Stamper(args)

Bases: object

Stamper is a utility class that can be used to stamp PDF pages with text, images, or vector art (including another PDF page) in only a few lines of code.

Although Stamper is very simple to use compared to ElementBuilder/ElementWriter it is not as powerful or flexible. In case you need full control over PDF creation use ElementBuilder/ElementWriter to add new content to existing PDF pages as shown in the ElementBuilder sample project.

static DeleteStamps(doc, page_set)

Deletes PDFTron stamps from document at given page numbers

Parameters:

• doc (PDFDoc) – The document to delete stamps from

• page_set (PageSet) – The set of pages to delete stamps from

Destroy()

Frees the native memory of the object.

static HasStamps(doc, page_set)

Returns true if the given set of pages has at least one stamp

Parameters:

• doc (PDFDoc) – The document that’s being checked

• page_set (PageSet) – The set of page that’s being checked

SetAlignment(horizontal_alignment, vertical_alignment)

Sets the alignment for the x and y variables.

See also: SetPosition

Parameters:

• horizontal_alignment (int) –

  Can be set to e_left, e_center or e_right e_left: horizontal_distance measures the distance between the left edge of the stamp’s

  bounding box and the left edge of the crop box

  e_center: horizontal_distance measures the distance between the horizontal bisector of the

  stamp’s bounding box and the horizontal bisector of the crop box

  e_right: horizontal_distance measures the distance between the right edge of the stamp’s

  bounding box and the right edge of the crop box

• vertical_alignment (int) –

  Can be set to e_top, e_center or e_bottom e_bottom: vertical_distance measures the distance between the bottom edge of the stamp’s

  bounding box and the bottom edge of the crop box

  e_center: vertical_distance measures the distance between the vertical bisector of the

  stamp’s bounding box and the vertical bisector of the crop box

  e_top: vertical_distance measures the distance between the top edge of the stamp’s

  bounding box and the top edge of the crop box

SetAsAnnotation(annotation)

Specifies if the stamp is to be stamped as an annotation.

Parameters:

annotation (boolean) – A flag specifying if the stamp should be added as an annotation or not

Notes: Stamps created with this setting do not work with SetAsBackground, HasStamps, and DeleteStamps, if annotation is true.

SetAsBackground(background)

Specifies if the stamp is to be stamped in the background or the foreground.

Parameters:

background (boolean) – A flag specifying if the stamp should be added as a background layer to the destination page

SetFont(font)

Defines the font of the stamp. (This only applies to text-based stamps)

Parameters:

font (Font) – The font of the text stamp

SetFontColor(color)

Sets the font color (This only effects text-based stamps)

Parameters:

font_color – The color of the font

SetOpacity(opacity)

Sets the opacity value for the stamp

Parameters:

opacity (double) – The opacity value of the stamp

SetPosition(horizontal_distance, vertical_distance, use_percentage=False)

Sets the horizontal and vertical position of the stamp.

See also: SetAlignment

Parameters:

• horizontal_distance (double) – Horizontal distance from left, right or center of crop box

• vertical_distance (double) – Vertical distance from top, bottom or center of crop box

• use_percentage (boolean) – If true, horizontal_distance is a percentage of the crop box width (e.g.: 0.5 is 50% of the width of the crop box) and vertical_distance is a percentage of the crop box height. If false, horizontal_distance and vertical_distance is measured in points.

SetRotation(rotation)

Rotates the stamp by the given number of degrees

Parameters:

rotation (double) – Rotation in degrees

SetSize(size_type, a, b)

Sets the size of the stamp

Parameters:

• size_type (int) –

  Specifies how the stamp will be sized -e_relative_scale: Stamp size is relative to the size of the crop box of the destination page. ‘a’ is a percentage of the width of the crop box (e.g.: 0.5 is 50% of the width of the crop box) ‘b’ is a percentage of the height of the crop box. If ‘a’ <= 0 then only b will be used. If ‘b’ <= 0 then only ‘a’ will be used.

  -e_absolute_scale: Stamp size is explicitly set. ‘a’ sets the width of of the stamp’s bounding box. ‘b’ sets the height of the stamp’s bounding box. The width and height areant, regardless of the size of the destination page’s bounding box.

  -e_font_size: This type only applies to text stamps. ‘a’ sets the font size. ‘b’ is ignored.

• a (double) – Generally the horizontal component of the size. See size_type for more details.

• b (double) – Generally the vertical component of the size. See size_type for more details.

SetTextAlignment(text_alignment)

Sets the text alignment (note: this only applies to text watermarks)

Parameters:

text_alignment (int) – Enumerator for text alignment (e_left, e_center, e_right)

ShowsOnPrint(on_print)

Parameters:

on_print (boolean) – Specifies if the watermark will be displayed when printed

ShowsOnScreen(on_screen)

Parameters:

on_screen (boolean) – Specifies if the watermark will be displayed on screen

StampImage(dest_doc, src_img, dest_pages)

Stamps an image to the given destination document at the set of page numbers

Parameters:

• dest_doc (PDFDoc) – The document being stamped

• src_img (Image) – The image that is being stamped to the document

• dest_pages (PageSet) – The set of pages in the document being stamped

StampPage(dest_doc, src_page, dest_pages)

Stamps a PDF page to the given destination document at the set of page numbers

Parameters:

• dest_doc (PDFDoc) – The document being stamped

• src_page (Page) – The page that is being stamped to the document

• dest_pages (PageSet) – The set of pages in the document being stamped

StampText(dest_doc, src_txt, dest_pages)

Stamps text to the given destination document at the set of page numbers

Parameters:

• dest_doc (PDFDoc) – The document being stamped

• src_txt (string) – The image that is being stamped to the document

• dest_pages (PageSet) – The set of pages in the document being stamped

e_absolute_size = 2

e_align_center = 0

e_align_left = -1

e_align_right = 1

e_font_size = 3

e_horizontal_center = 0

e_horizontal_left = -1

e_horizontal_right = 1

e_relative_scale = 1

e_vertical_bottom = -1

e_vertical_center = 0

e_vertical_top = 1

property mp_impl

property thisown

The membership flag

apryse_sdk.Stamper_DeleteStamps(doc, page_set)

Deletes PDFTron stamps from document at given page numbers

Parameters:

• doc (PDFDoc) – The document to delete stamps from

• page_set (PageSet) – The set of pages to delete stamps from

apryse_sdk.Stamper_HasStamps(doc, page_set)

Returns true if the given set of pages has at least one stamp

Parameters:

• doc (PDFDoc) – The document that’s being checked

• page_set (PageSet) – The set of page that’s being checked

class apryse_sdk.StrikeOut(args)

Bases: TextMarkup

A StrikeOut annotation shows as a line segment crossing out a word or a group of contiguous words.

static Create(doc, pos)

Creates a new StrikeOut annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the Popup annotation is added.

• pos (Rect) – A rectangle specifying the Popup annotation’s bounds in default user space units.

Return type:

StrikeOut

Returns:

A newly created blank StrikeOut annotation.

static CreateAnnot(doc, pos)

property thisown

The membership flag

apryse_sdk.StrikeOut_Create(doc, pos)

Creates a new StrikeOut annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the Popup annotation is added.

• pos (Rect) – A rectangle specifying the Popup annotation’s bounds in default user space units.

Return type:

StrikeOut

Returns:

A newly created blank StrikeOut annotation.

apryse_sdk.StrikeOut_CreateAnnot(doc, pos)

class apryse_sdk.StructuredOutputModule

Bases: object

The class StructuredOutputModule. static interface to PDFTron SDKs PDF to Word, Excel, PowerPoint, HTML functionality

static IsModuleAvailable()

Find out whether the StructuredOutput add-on module is available (and licensed).

Return type:

boolean

Returns:

returns true if StructuredOutput operations can be performed.

property thisown

The membership flag

apryse_sdk.StructuredOutputModule_IsModuleAvailable()

Find out whether the StructuredOutput add-on module is available (and licensed).

Return type:

boolean

Returns:

returns true if StructuredOutput operations can be performed.

class apryse_sdk.Style(args)

Bases: object

A class representing predominant text style associated with a given Line, a Word, or a Glyph. The class includes information about the font, font size, font styles, text color, etc.

GetColor()

Return type:

std::vector< int,std::allocator< int > >

Returns:

text color in RGB color space.

GetFont()

Return type:

Obj

Returns:

low-level PDF font object. A high level font object can be instantiated as follows: In C++: pdftron.PDF.Font f(style.GetFont()) In C#: pdftron.PDF.Font f = new pdftron.PDF.Font(style.GetFont());

GetFontName()

Return type:

string

Returns:

the font name used to draw the selected text.

GetFontSize()

Return type:

double

Returns:

The font size used to draw the selected text as it appears on the output page.

Notes: Unlike the ‘font size’ in the graphics state (pdftron.PDF.GState) the returned font size accounts for the effects CTM, text matrix, and other graphics state attributes that can affect the appearance of text.

GetWeight()

Return type:

int

Returns:

The weight (thickness) component of the fully-qualified font name or font specifier. The possible values are 100, 200, 300, 400, 500, 600, 700, 800, or 900, where each number indicates a weight that is at least as dark as its predecessor. A value of 400 indicates a normal weight; 700 indicates bold. Note: The specific interpretation of these values varies from font to font. For example, 300 in one font may appear most similar to 500 in another.

IsItalic()

Return type:

boolean

Returns:

true if glyphs have dominant vertical strokes that are slanted.

Notes: the return value corresponds to the state of ‘italic’ flag in the ‘Font Descriptor’.

IsSerif()

Return type:

boolean

Returns:

true if glyphs have serifs, which are short strokes drawn at an angle on the top and bottom of glyph stems.

Notes: the return value corresponds to the state of ‘serif’ flag in the ‘Font Descriptor’.

property mp_style

property thisown

The membership flag

class apryse_sdk.SwigPyIterator(args, kwargs)

Bases: object

advance(n)

copy()

decr(n=1)

distance(x)

equal(x)

incr(n=1)

next()

previous()

property thisown

The membership flag

value()

class apryse_sdk.TOCSettings

Bases: object

Settings for table of contents.

This option is deprecated in the latest HTML2PDF module and may have no effect.

Destroy()

Frees the native memory of the object.

SetCaptionText(caption)

Caption text to be used with TOC.

Parameters:

caption (string) –

• Text that will appear with the table of contents.

Notes: This option is deprecated in the latest HTML2PDF module and may have no effect.

SetDottedLines(enable)

Use a dotted line when creating TOC.

Parameters:

enable (boolean) –

• Table of contents will use dotted lines.

Notes: This option is deprecated in the latest HTML2PDF module and may have no effect.

SetLevelIndentation(indentation)

Indentation used for every TOC level…

Parameters:

indentation (int) –

• How much to indent each level, e.g. “2”

Notes: This option is deprecated in the latest HTML2PDF module and may have no effect.

SetLinks(enable)

Create links from TOC to actual content.

Parameters:

enable (boolean) –

• Entries in table of contents will

link to section in the PDF.

Notes: This option is deprecated in the latest HTML2PDF module and may have no effect.

SetTextSizeShrink(shrink)

How much to shrink font for every level, e.g. 0.8

Parameters:

shrink (double) –

• Rate at which lower level entries will appear smaller

Notes: This option is deprecated in the latest HTML2PDF module and may have no effect.

SetXsl(style_sheet)

xsl style sheet used to convert outline XML into a table of content.

Parameters:

style_sheet (string) –

• Path to xsl style sheet to be used to generate

this table of contents.

Notes: This option is deprecated in the latest HTML2PDF module and may have no effect.

property mp_impl

property thisown

The membership flag

class apryse_sdk.TRN_byterange

Bases: object

property m_offset

property m_size

property thisown

The membership flag

class apryse_sdk.TRN_chardata

Bases: object

property bytes

property char_code

property char_data

property thisown

The membership flag

property x

property y

class apryse_sdk.TRN_date

Bases: object

property UT

property UT_hour

property UT_minutes

property day

property hour

property minute

property month

property mp_obj

property second

property thisown

The membership flag

property year

class apryse_sdk.TRN_matrix2d

Bases: object

property m_a

property m_b

property m_c

property m_d

property m_h

property m_v

property thisown

The membership flag

class apryse_sdk.TRN_point

Bases: object

property thisown

The membership flag

property x

property y

class apryse_sdk.TRN_quadpoint

Bases: object

property p1x

property p1y

property p2x

property p2y

property p3x

property p3y

property p4x

property p4y

property thisown

The membership flag

class apryse_sdk.TRN_rect

Bases: object

property mp_rect

property thisown

The membership flag

property x1

property x2

property y1

property y2

class apryse_sdk.Table(args, kwargs)

Bases: ContentNode

A Table is a content node that contains a grid of cells.

AddTableRow()

Add a new row to the table

Return type:

TableRow

Returns:

The newly created row

Destroy()

GetBorderThickness()

Get the border thickness of the table

Return type:

double

Returns:

border thickness in points

GetDefaultRowHeight()

Get default row height of the table

Return type:

double

Returns:

Default row height of the table

GetNumColumns()

Get the number of rows in the table

Return type:

int

Returns:

number of rows in the table

GetNumRows()

Get the number of rows in the table

Return type:

int

Returns:

number of rows in the table

GetTableCell(column, row)

Get a cell from the table

Parameters:

• column (int) – The column index of the cell to retrieve

• row (int) – The row index of the cell to retrieve

Return type:

TableCell

Returns:

the TableCell at the specified column and row

SetBorder(thickness, red, green, blue)

Set the cell’s border thickness and color

Parameters:

• thickness (double) – The thickness of the border in points

• red (int) – The red component of the border color

• green (int) – The green component of the border color

• blue (int) – The blue component of the border color

SetDefaultColumnWidth(val)

Set default column weight of the table

Parameters:

val (double) – The default column weight

SetDefaultRowHeight(val)

Set default row height of the table

Parameters:

val (double) – The default row height

property thisown

The membership flag

class apryse_sdk.TableCell(args, kwargs)

Bases: ContentNode

A class representing a table cell, which can be used during document creation.

AddParagraph(args)

Overload 1:

Add an empty paragraph to the cell

Return type:

Paragraph

Returns:

The paragraph that was added

Overload 2:

Add a paragraph with text to the cell

Return type:

Paragraph

Returns:

The paragraph that was added

AddTable()

Add a nested table to the cell

Return type:

Table

Returns:

The table that was added

Destroy()

GetBorderThickness()

Get the border thickness of the table cell

Return type:

double

Returns:

border thickness

GetHeight()

Get the height of the cell

Return type:

double

Returns:

the height of the cell

GetHorizontalAlignment()

Get the horizontal alignment of the cell

Return type:

int

Returns:

the horizontal Alignment of the cell

GetVerticalAlignment()

Get the vertical alignment of the cell

Return type:

int

Returns:

the vertical alignment of the cell

GetWidth()

Get the width of the cell

Return type:

double

Returns:

the width of the cell

MergeCellsDown(num)

Merge the cell with the specified number of cells downwards

Return type:

TableCell

Returns:

The merged cell

MergeCellsRight(num)

Merge the cell with the specified number of cells to the right

Return type:

TableCell

Returns:

The merged cell

SetBackgroundColor(red, green, blue)

Set the background color of the cell

Parameters:

• red (int) – The red component of the border color

• green (int) – The green component of the border color

• blue (int) – The blue component of the border color

SetBorder(thickness, red, green, blue)

Set the cell’s border thickness and color

Parameters:

• thickness (double) – The thickness of the border

• red (int) – The red component of the border color

• green (int) – The green component of the border color

• blue (int) – The blue component of the border color

SetHeight(val)

Set the height of the cell

Parameters:

val (double) – The height of the cell

SetHorizontalAlignment(val)

Set horizontal alignment of the cell

Parameters:

val (int) – The horizontal alignment of the cell

SetVerticalAlignment(val)

Set the vertical alignment of the cell

Parameters:

val (int) – The vertical alignment of the cell

SetWidth(val)

Set the width of the cell

Parameters:

val (double) – The width of the cell

e_alignment_bottom = 3

Cell content is bottom-aligned

e_alignment_center = 2

Cell content is vertically centered

e_alignment_left = 1

Cell content is left-aligned

e_alignment_middle = 2

Cell content is horizontally centered

e_alignment_right = 3

Cell content is right-aligned

e_alignment_top = 1

Cell content is top-aligned

property thisown

The membership flag

class apryse_sdk.TableRow(args, kwargs)

Bases: ContentNode

A class representing a table row, which can be used during document creation.

AddTableCell()

Add a new cell to the row

Return type:

TableCell

Returns:

The newly created cell

Destroy()

GetNumColumns()

Get number of columns in the row

Because of cell merging different rows may have different numbers of columns.

Return type:

int

Returns:

number of columns in the row

SetRowHeight(val)

Set row height

Parameters:

val (double) – The row height

property thisown

The membership flag

class apryse_sdk.TemplateDocument(args)

Bases: object

The class TemplateDocument. Encapsulates a template document that can merged with data to generate any number of PDFs.

TemplateDocument instances are created through the Convert class. See Convert.CreateOfficeTemplate.

CancelConversion()

Cancel the current template filling, forcing FillTemplateJson to return.

static CreateInternal(impl)

Destroy()

FillTemplateJson(json)

Create a PDF by merging JSON data with this template document.

Parameters:

json (string) – – A JSON dictionary mapping template keys to their replacement content.

Return type:

PDFDoc

Returns:

The PDFDoc from the template filling result.

FillTemplateJsonToOffice(json, output_path)

Create an office file by merging JSON data with this template document. This function currently only supports DOCX input.

Parameters:

• json (string) – – A JSON dictionary mapping template keys to their replacement content.

• output_path (string) – – The path where the output file is written.

GetConversionStatus()

Get the state of the template filling process.

Return type:

int

Returns:

.

GetErrorString()

If the template filling finsihed with some kind of error, this returns the value of the error description; otherwise returns an empty string.

Return type:

string

Returns:

The error description. Will be blank unless GetConversionStatus returns Failure.

GetHandleInternal()

GetNumWarnings()

Return the number of warning strings generated during the template filling process. Warning: experimental interface; this method may be renamed or replaced with equivalent functionality in the future.

Return type:

int

Returns:

The number of stored warning strings.

GetTemplateKeysJson()

Get information about the template keys present in the template document. Returns a JSON dictionary following this form: https://www.pdftron.com/api/web/Core.html#.TemplateSchema.

Return type:

string

Returns:

The template keys info JSON dictionary, serialized into a string.

GetWarningString(index)

Retrieve warning strings that have been collected during the template filling process. Warning: experimental interface; this method may be renamed or replaced with equivalent functionality in the future.

Parameters:

index (int) – – the index of the string to be retrieved. Must be less than GetNumWarnings().

Return type:

string

Returns:

The value of the particular warning string.

IsCancelled()

Has the template filling been cancelled?.

Return type:

boolean

Returns:

Returns true if CancelConversion has been called previously.

eFailure = 2

eIncomplete = 1

eSuccess = 0

property m_impl

property thisown

The membership flag

apryse_sdk.TemplateDocument_CreateInternal(impl)

class apryse_sdk.Text(args)

Bases: Markup

A text annotation represents a “sticky note” attached to a point in the PDF document. When closed, the annotation shall appear as an icon; when open, it shall display a pop-up window containing the text of the note in a font and size chosen by the conforming reader. Text annotations do not scale and rotate with the page (i.e. they should behave as if the NoZoom and NoRotate annotation flags).

static Create(args)

Overload 1:

Creates a new Text annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds in default user space units.

Return type:

Text

Returns:

A newly created blank Text annotation.

Creates a new Text annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds in default user space units.

• contents (string) – The text of the annotation, that shall be displayed in its popup window.

Return type:

Text

Returns:

A newly created Text annotation.

Overload 2:

Creates a new Text annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Point) – A point specifying the annotation’s location in default user space units. This determines the location of bottom left corner of the annotation’s icon.

• contents (string) – The text of the annotation, that shall be displayed in its popup window.

Return type:

Text

Returns:

A newly created Text annotation.

Overload 3:

Creates a new Text annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Point) – A point specifying the annotation’s location in default user space units. This determines the location of bottom left corner of the annotation’s icon.

• contents – The text of the annotation, that shall be displayed in its popup window.

Return type:

Text

Returns:

A newly created Text annotation.

static CreateAnnot(args)

GetAnchorPosition()

Returns anchor point position (in relative coordinates) - the point that won’t move when the page is zoomed in/out Anchor point position is in relative coordinates [0,1], and default is upper-left corner (0,1)

Return type:

Point

Returns:

Currently stored anchor position or the default (upper-left corner (0,1))

GetIcon()

Returns the type of the icon associated with the Text annotation.

Return type:

int

Returns:

A value of the enumeration type “Icon”. Default value: e_Note.

Notes: The annotation’s appearance stream, if present, will take precedence over this entry.

GetIconName()

Returns the name of the icon associated with the Text annotation.

Return type:

string

Returns:

A string denoting the name of the icon.

Notes: The following icon names are equivalent to predefined icon types from the enum “Icon”: “Comment” = e_Comment “Key” = e_Key “Help” = e_Help “NewParagraph” = e_NewParagraph “Paragraph” = e_Paragraph “Insert” = e_Insert “Note” = e_Note “Unknown” = e_Unknown Names other than mentioned above do not have predefined icon appearances. The annotation’s appearance stream, if present, will take precedence over this entry.

GetState()

Returns the string indicating the state of the Text annotation. (PDF 1.5)

Return type:

string

Returns:

A string that indicates the state of the Text annotation when first loaded. Default: “Unmarked” if StateModel is “Marked”; “None” if StateModel is “Review”.

GetStateModel()

Returns the string indicating the state model of the Text annotation. (PDF 1.5)

Return type:

string

Returns:

A string containing the state model name - either “Marked” or “Review”.

IsOpen()

Returns the initial status of the Text annotation.

Return type:

boolean

Returns:

A boolean value that specifies whether the annotation shall initially be displayed as opened. Default value: false.

SetAnchorPosition(pt)

Sets anchor point position (in coordinates relative to the annotation Rect) - the point that won’t move when the page is zoomed in/out and/or if the page is rotated.

Parameters:

pt (Point) – Anchor point position in relative coordinates [0,1], where 0,0 is bottom left corner of the annotation, and 1,1 is top right corner. Default: 0,1

SetIcon(args)

Overload 1:

Sets the type of the icon associated with the Text annotation. (Optional)

Parameters:

icon (int) – A value of the enum “Icon” type. Default value: e_Note.

Notes: The annotation’s appearance stream, if present, will take precedence over this entry.

Overload 2:

Sets the name of the icon associated with the Text annotation. (Optional)

Parameters:

icon (string) – A string denoting the name of the icon.

Notes: The following icon names are equivalent to predefined icon types from the enum “Icon”: “Comment” = e_Comment “Key” = e_Key “Help” = e_Help “NewParagraph” = e_NewParagraph “Paragraph” = e_Paragraph “Insert” = e_Insert “Note” = e_Note “Unknown” = e_Unknown Names other than mentioned above do not have predefined icon appearances. The annotation’s appearance stream, if present, will take precedence over this entry.

SetOpen(isopen)

Sets the initial status of the Text annotation. (Optional)

Parameters:

isopen (boolean) – A boolean value that specifies whether the annotation shall initially be displayed as opened. Default value: false.

SetState(args)

Sets the string indicating the state of the Text annotation. (Optional; PDF 1.5 )

Parameters:

state (string) – A string that indicates the state of the Text annotation when first loaded. Default: “Unmarked” if StateModel is “Marked”; “None” if StateModel is “Review”.

SetStateModel(sm)

Sets the string indicating the state model of the Text annotation. (Required if State is present, otherwise optional; PDF 1.5 )

Parameters:

sm (string) – A string containing the state model name - either “Marked” or “Review”.

e_Comment = 0

comment icon

e_Help = 2

Help icon

e_Insert = 5

Insert icon

e_Key = 1

key icon

e_NewParagraph = 3

New Paragraph icon

e_Note = 6

Note icon

e_Paragraph = 4

Paragraph icon

e_Unknown = 7

Unknown, no icon associated or non-standard icon.

property thisown

The membership flag

class apryse_sdk.TextDiffOptions

Bases: object

AddIgnoreZonesForPage(regions, page_num)

Adds a collection of ignorable regions for the given page, an optional list of page areas not to be included in analysis

Parameters:

• regions: – the zones to be added to the ignore list

• page_num: – the page number the added regions belong to

Return type:

TextDiffOptions

Returns:

this object, for call chaining

GetColorA()

Gets the value ColorA from the options object The difference color for deletions

Return type:

ColorPt

Returns:

a ColorPt, the current value for ColorA in the form of R, G, B

GetColorB()

Gets the value ColorB from the options object The difference color for insertions

Return type:

ColorPt

Returns:

a ColorPt, the current value for ColorB in the form of R, G, B

GetCompareStyles()

Gets the value CompareStyles from the options object Whether to highlight text style differences. Off by default. Text style includes font, size, bold, italic and text color. For example, if a word is italic in document A and is bold in document B, we can highlight the location of the word in both documents.

Return type:

boolean

Returns:

a bool, the current value for CompareStyles.

GetCompareUsingZOrder()

Gets the value CompareUsingZOrder from the options object Whether to use z-order (aka paint order) when comparing text between A and B. On by default.

Return type:

boolean

Returns:

a bool, the current value for CompareUsingZOrder.

GetExtraMoveColor()

Gets the value ExtraMoveColor from the options object The difference color for extra moves

Return type:

ColorPt

Returns:

a ColorPt, the current value for ExtraMoveColor in the form of R, G, B

GetExtraMoveHighlight()

Gets the value ExtraMoveHighlight from the options object Whether to highlight text in between short-distance moves when comparing text between A and B. Off by default.

Return type:

boolean

Returns:

a bool, the current value for ExtraMoveHighlight.

GetExtraMoveOpacity()

Gets the value ExtraMoveOpacity from the options object The difference opacity for extra moves

Return type:

double

Returns:

a double, the current value for ExtraMoveOpacity in between 0.0 (transparent) and 1.0 (opaque)

GetInternalObj(args)

GetOpacityA()

Gets the value OpacityA from the options object The difference opacity for deletions

Return type:

double

Returns:

a double, the current value for OpacityA in between 0.0 (transparent) and 1.0 (opaque)

GetOpacityB()

Gets the value OpacityB from the options object The difference opacity for insertions

Return type:

double

Returns:

a double, the current value for OpacityB in between 0.0 (transparent) and 1.0 (opaque)

GetShowPlaceholders()

Gets the value ShowPlaceholders from the options object Whether to show placeholder annotations. On by default. Placeholders are insertion locations in document A and deletion locations in document B. For example, if a word is removed from document B, we can highlight the location of the original word in document A, but there is no word to highlight in B (it’s removed). In this case a small “placeholder” annotation is placed in B to identify the location of the removal.

Return type:

boolean

Returns:

a bool, the current value for ShowPlaceholders.

SetColorA(color)

Sets the value for ColorA in the options object The difference color for deletions

Parameters:

color: – the new value for ColorA in the form of R, G, B

Return type:

TextDiffOptions

Returns:

this object, for call chaining

SetColorB(color)

Sets the value for ColorB in the options object The difference color for insertions

Parameters:

color: – the new value for ColorB in the form of R, G, B

Return type:

TextDiffOptions

Returns:

this object, for call chaining

SetCompareStyles(value)

Sets the value for CompareStyles in the options object Whether to highlight text style differences. Off by default. Text style includes font, size, bold, italic and text color. For example, if a word is italic in document A and is bold in document B, we can highlight the location of the word in both documents.

Parameters:

value: – the new value for CompareStyles

Return type:

TextDiffOptions

Returns:

this object, for call chaining

SetCompareUsingZOrder(value)

Sets the value for CompareUsingZOrder in the options object Whether to use z-order (aka paint order) when comparing text between A and B. On by default.

Parameters:

value: – the new value for CompareUsingZOrder

Return type:

TextDiffOptions

Returns:

this object, for call chaining

SetExtraMoveColor(color)

Sets the value for ExtraMoveColor in the options object The difference color for extra moves

Parameters:

color: – the new value for ExtraMoveColor in the form of R, G, B

Return type:

TextDiffOptions

Returns:

this object, for call chaining

SetExtraMoveHighlight(value)

Sets the value for ExtraMoveHighlight in the options object Whether to highlight text in between short-distance moves when comparing text between A and B. Off by default.

Parameters:

value: – the new value for ExtraMoveHighlight

Return type:

TextDiffOptions

Returns:

this object, for call chaining

SetExtraMoveOpacity(opacity)

Sets the value for ExtraMoveOpacity in the options object The difference opacity for extra moves

Parameters:

opacity: – the new value for ExtraMoveOpacity in between 0.0 (transparent) and 1.0 (opaque)

Return type:

TextDiffOptions

Returns:

this object, for call chaining

SetOpacityA(opacity)

Sets the value for OpacityA in the options object The difference opacity for deletions

Parameters:

opacity: – the new value for OpacityA in between 0.0 (transparent) and 1.0 (opaque)

Return type:

TextDiffOptions

Returns:

this object, for call chaining

SetOpacityB(opacity)

Sets the value for OpacityB in the options object The difference opacity for insertions

Parameters:

opacity: – the new value for OpacityB in between 0.0 (transparent) and 1.0 (opaque)

Return type:

TextDiffOptions

Returns:

this object, for call chaining

SetShowPlaceholders(value)

Sets the value for ShowPlaceholders in the options object Whether to show placeholder annotations. On by default. Placeholders are insertion locations in document A and deletion locations in document B. For example, if a word is removed from document B, we can highlight the location of the original word in document A, but there is no word to highlight in B (it’s removed). In this case a small “placeholder” annotation is placed in B to identify the location of the removal.

Parameters:

value: – the new value for ShowPlaceholders

Return type:

TextDiffOptions

Returns:

this object, for call chaining

property thisown

The membership flag

class apryse_sdk.TextExtractor

Bases: object

TextExtractor is used to analyze a PDF page and extract words and logical structure within a given region. The resulting list of lines and words can be traversed element by element or accessed as a string buffer. The class also includes utility methods to extract PDF text as HTML or XML.

Possible use case scenarios for TextExtractor include:

• Converting PDF pages to text or XML for content repurposing.

• Searching PDF pages for specific words or keywords.

• Indexing large PDF repositories for indexing or content retrieval purposes (i.e. implementing a PDF search engine).

• Classifying or summarizing PDF documents based on their text content.

• Finding specific words for content editing purposes (such as splitting pages based on keywords etc).

The main task of TextExtractor is to interpret PDF pages and offer a simple to use API to:

• Normalize all text content to Unicode.

• Extract inferred logical structure (word by word, line by line, or paragraph by paragraph).

• Extract positioning information for every line, word, or a glyph.

• Extract style information (such as information about the font, font size, font styles, etc) for every line, word, or a glyph.

• Control the content analysis process. A number of options (such as removal of text obscured by images) is available to let the user direct the flow of content recognition algorithms that will meet their requirements.

• Offer utility methods to convert PDF page content to text, XML, or HTML.

Note: TextExtractor is analyzing only textual content of the page. This means that the rasterized (e.g. in scanned pages) or vectorized text (where glyphs are converted to path outlines) will not be recognized as text. Please note that it is still possible to extract this content using pdftron.PDF.ElementReader interface.

In some cases TextExtractor may extract text that does not appear to be on the visible page (e.g. when text is obscured by an image or a rectangle). In these situations it is possible to use processing flags such as ‘e_remove_hidden_text’ and ‘e_no_invisible_text’ to remove hidden text.

A sample use case (in C++):

... Initialize PDFNet ...
PDFDoc doc(filein);
doc.InitSecurityHandler();
Page page = doc.PageBegin();
TextExtractor txt;
txt.Begin(page, 0, TextExtractor::e_remove_hidden_text);
UString text;
txt.GetAsText(text);
// or traverse words one by one...
TextExtractor::Line line = txt.GetFirstLine(), lend;
TextExtractor::Word word, wend;
for (; line!=lend; line=line.GetNextLine()) {
 for (word=line.GetFirstWord(); word!=wend; word=word.GetNextWord()) {
   text.Assign(word.GetString(), word.GetStringLen());
   cout < text < '';
 }
}

A sample use case (in C#):

... Initialize PDFNet ...
PDFDoc doc = new PDFDoc(filein);
doc.InitSecurityHandler();
Page page = doc.PageBegin().Current();
TextExtractor txt = new TextExtractor();
txt.Begin(page, 0, TextExtractor.ProcessingFlags.e_remove_hidden_text);
string text = txt.GetAsText();
// or traverse words one by one...
TextExtractor.Word word;
for (TextExtractor.Line line = txt.GetFirstLine(); line.IsValid(); line=line.GetNextLine()) {
  for (word=line.GetFirstWord(); word.IsValid(); word=word.GetNextWord()) {
    Console.WriteLine(word.GetString());
  }
}

For full sample code, please take a look at TextExtract sample project.

Begin(page, clip_ptr=None, flags=0)

Start reading the page.

Parameters:

• page (Page) – Page to read.

• clip_ptr (Rect) – A pointer to the optional clipping rectangle. This parameter can be used to selectively read text from a given rectangle.

• flags (int) – A list of ProcessingFlags used to control text extraction algorithm.

Destroy()

Frees the native memory of the object.

GetAsText(dehyphen=True)

Get all words in the current selection as a single string.

Parameters:

• out_str – The string containing all words in the current selection. Words will be separated with space (i.e. ‘ ‘) or new line (i.e. ‘ ‘) characters.

• dehyphen (boolean) – If true, finds and removes hyphens that split words across two lines. Hyphens are often used a the end of lines as an indicator that a word spans two lines. Hyphen detection enables removal of hyphen character and merging of text runs to form a single word. This option has no effect on Tagged PDF files.

GetAsXML(xml_output_flags=0)

Get text content in a form of an XML string.

Parameters:

• out_xml –

  • The string containing XML output.

• xml_output_flags (int) –

  • flags controlling XML output. For more

  information, please see TextExtract::XMLOutputFlags.

XML output will be encoded in UTF-8 and will have the following structure:

Page num="1 crop_box="0, 0, 612, 792" media_box="0, 0, 612, 792" rotate="0">
 <Flow id="1">
  <Para id="1">
   <Line box="72, 708.075, 467.895, 10.02" style="font-family:Calibri; font-size:10.02; color: #000000;">
     <Word box="72, 708.075, 30.7614, 10.02">PDFNet</Word>
     <Word box="106.188, 708.075, 15.9318, 10.02">SDK</Word>
     <Word box="125.617, 708.075, 6.22242, 10.02">is</Word>
     ...
   </Line>
  </Para>
 </Flow>
</Page>
@endcode

The above XML output was generated by passing the following union of
flags in the call to GetAsXML():
  (TextExtractor::e_words_as_elements | TextExtractor::e_output_bbox | TextExtractor::e_output_style_info)

In case 'xml_output_flags' was not specified, the default XML output
would look as follows:

<Page num="1 crop_box="0, 0, 612, 792" media_box="0, 0, 612, 792" rotate="0"
Flow id="1"
Para id="1"
    LinePDFNet SDK is an amazingly comprehensive, high-quality PDF developer toolkit...Line
    Linelevels. Using the PDFNet PDF library, ...Line
    ...
  Para
 Flow
Page

GetFirstLine()

Return type:

Line

Returns:

The first line of text on the selected page.

Notes: To traverse the list of all text lines on the page use line.GetNextLine(). To traverse the list of all word on a given line use line.GetFirstWord().

GetHighlights(char_ranges)

Get a Highlights object based on an array of character ranges.

Parameters:

char_ranges (std::vector< PDF::CharRange,std::allocator< PDF::CharRange > >) – an array of character ranges to be highlighted

Return type:

Highlights

Returns:

a Highlights object containing the selected characters

GetNumLines()

Return type:

int

Returns:

The number of lines of text on the selected page.

GetRightToLeftLanguage()

Return type:

boolean

Returns:

the directionality of text extractor.

GetTextUnderAnnot(annot)

Get all the characters that intersect an annotation.

Parameters:

annot (Annot) – The annotation to intersect with.

GetWordCount()

Return type:

int

Returns:

the number of words on the page.

SetOCGContext(ctx)

Sets the Optional Content Group (OCG) context that should be used when processing the document. This function can be used to change the current OCG context. Optional content (such as PDF layers) will be selectively processed based on the states of optional content groups in the given context.

Parameters:

ctx (Context) – Optional Content Group (OCG) context, or NULL if TextExtractor should process all content on the page.

SetRightToLeftLanguage(rtl)

Sets the directionality of text extractor. Must be called before the processing of a page started.

Parameters:

rtl (boolean) – mode reverses the directionality of TextExtractor algorithm.

e_extract_using_zorder = 256

e_no_dup_remove = 2

e_no_invisible_text = 16

e_no_ligature_exp = 1

e_no_watermarks = 128

e_output_bbox = 2

e_output_style_info = 4

e_punct_break = 4

e_remove_hidden_text = 8

e_words_as_elements = 1

property thisown

The membership flag

class apryse_sdk.TextMarkup(args)

Bases: Markup

A TextMarkup is a base class for highlight, underline, strikeout, and squiggly annotations.

GetQuadPoint(idx)

Returns the QuadPoint located at a certain index of the QuadPoint array. (PDF 1.6)

Parameters:

idx (int) – The index where the QuadPoint is located. The index starts at zero and must be less than return value of GetQuadPointCount().

Return type:

QuadPoint

Returns:

The QuadPoint located at a certain index of the QuadPoint array of the TextMarkup annotation.

Notes: QuadPoints specify the coordinates of quadrilaterals in default user space. Each quadrilateral encompasses a word or group of contiguous words in the text underlying the annotation. The four points(p1, p2, p3, p4) of a QuadPoint specify the quadrilateral’s four vertices in counterclockwise order. The text needs to be oriented with respect to the edge connecting points (p1) and (p2). The annotation dictionary’s Appearance entry, if present, takes precedence over QuadPoints.

GetQuadPointCount()

Returns the number of QuadPoints in the QuadPoints array of the TextMarkup annotation (PDF 1.6)

Return type:

int

Returns:

The number of QuadPoints.

Notes: QuadPoints specify the coordinates of quadrilaterals in default user space. Each quadrilateral encompasses a word or group of contiguous words in the text underlying the annotation. The four points(p1, p2, p3, p4) of a QuadPoint specify the quadrilateral’s four vertices in counterclockwise order. The text needs to be oriented with respect to the edge connecting points (p1) and (p2). The annotation dictionary’s Appearance entry, if present, takes precedence over QuadPoints.

SetQuadPoint(idx, qp)

Sets the QuadPoint to be located at a certain index of the QuadPoint array. (Optional; PDF 1.6 )

Parameters:

• idx (int) – The index where the QuadPoint is to be located (the index is counted from 0).

• qp (QuadPoint) – The QuadPoint to be located at a certain index of the QuadPoint array of the TextMarkup annotation.

To make this QuadPoint compatible with Adobe Acrobat|Reader, you can use either clockwise or counterclockwise order, but the points p3 and p4 must be swapped. This is because those readers do not follow the PDF specification for TextMarkup QuadPoints. Notes: An array of n QuadPoints specifying the coordinates of n quadrilaterals in default user space. Each quadrilateral shall encompasses a word or group of contiguous words in the text underlying the annotation. The coordinates for each quadrilateral shall be given in the order p1, p2, p3, p4 specifying the quadrilateral’s four vertices in counterclockwise order. The text shall be oriented with respect to the edge connecting points (p1) and (p2). The annotation dictionary’s Appearance(AP) entry, if present, shall take precedence over QuadPoints.

property thisown

The membership flag

class apryse_sdk.TextRange(args)

Bases: object

The TextRange class represents a contiguous range of text on a PDF page. It may be the result of a text search, or simply a couple of highlighted or underlined words.

Each text range contains a few pieces of information:

page: the number of the page this piece of text is on; position: the start position (text offset); length: the length.

You are able to retrieve further information about the text range, such as its coordinates, the text itself, as well as characters before and after.

static CreateInternal(impl)

Destroy()

Frees the native memory of the object.

GetHandleInternal()

GetPageNumber()

Get the page number of the text range.

GetQuads()

Get the corresponding quadrangles of the text range.

Return type:

std::vector< PDF::QuadPoint,std::allocator< PDF::QuadPoint > >

Returns:

the number of the resulting quadrangles. Each quadrangle has eight doubles (x1, y1), (x2, y2), (x3, y3), (x4, y4) denoting the four vertices in counter-clockwise order.

Notes: the ‘quads’ array is owned by the current TextRange and does not need to be explicitly released. Since a highlight may correspond to multiple quadrangles, e.g., when it crosses a line, the number of resulting quadrangles may be larger than 1.

GetText()

Get the Unicode string content of the text range.

Return type:

string

Returns:

the text within the range

GetTextAfter(count)

Get the Unicode string content immediately after the text range.

Parameters:

count (int) – the number of characters to retrieve before the text range

Return type:

string

Returns:

the text after the range

GetTextBefore(count)

Get the Unicode string content immediately before the text range.

Parameters:

count (int) – the number of characters to retrieve before the text range

Return type:

string

Returns:

the text before the range

property mp_textrange

property thisown

The membership flag

apryse_sdk.TextRange_CreateInternal(impl)

class apryse_sdk.TextRun(args, kwargs)

Bases: ContentElement

A TextRun is a content element that represents a single run of text. A paragraph can contain multiple TextRun objects.

Destroy()

GetText()

Get the text content of the TextRun object

Return type:

string

Returns:

The text content

SetText(text)

Set the text content of the TextRun object

Parameters:

text (string) – The text content to set

property thisown

The membership flag

class apryse_sdk.TextSearch

Bases: object

TextSearch searches through a PDF document for a user-given search pattern. The current implementation supports both verbatim search and the search using regular expressions, whose detailed syntax can be found at:

http://www.boost.org/doc/libs/release/libs/regex/doc/html/boost_regex/syntax/perl_syntax.html

TextSearch also provides users with several useful search modes and extra information besides the found string that matches the pattern. TextSearch can either keep running until a matched string is found or be set to return periodically in order for the caller to perform any necessary updates (e.g., UI updates). It is also worth mentioning that the search modes can be changed on the fly while searching through a document.

Possible use case scenarios for TextSearch include:

• Guide users of a PDF viewer (e.g. implemented by PDFViewCtrl) to places where they are intersted in;

• Find interested PDF documents which contain certain patterns;

• Extract interested information (e.g., credit card numbers) from a set of files;

• Extract Highlight information (refer to the Highlights class for details) from files for external use.

Note

• Since hyphens (‘-’) are frequently used in PDF documents to concatenate the two broken pieces of a word at the end of a line, for example

  “TextSearch is powerful for finding patterns in PDF files; yes, it is really pow-

  erful.”

  a search for “powerful” should return both instances. However, not all end-of-line hyphens are hyphens added to connect a broken word; some of them could be “real” hyphens. In addition, an input search pattern may also contain hyphens that complicate the situation. To tackle this problem, the following conventions are adopted:

  a)When in the verbatim search mode and the pattern contains no hyphen, a matching

  string is returned if it is exactly the same or it contains end-of-line or start-of-line hyphens. For example, as mentioned above, a search for “powerful” would return both instances.

  b)When in verbatim search mode and the pattern contains one or multiple hyphens, a

  matching string is returned only if the string matches the pattern exactly. For example, a search for “pow-erful” will only return the second instance, and a search for “power-ful” will return nothing.

  c)When searching using regular expressions, hyphens are not taken care implicitly.

  Users should take care of it themselves. For example, in order to find both the “powerful” instances, the input pattern can be “pow-{0,1}erful”.

A sample use case (in C++):

//... Initialize PDFNet ...
PDFDoc doc(filein);
doc.InitSecurityHandler();
int page_num;
char buf[32];
UString result_str, ambient_string;
Highlights hlts;
TextSearch txt_search;
TextSearch::Mode mode = TextSearch::e_whole_word | TextSearch::e_page_stop;
UString pattern( "joHn sMiTh" );

//PDFDoc doesn't allow simultaneous access from different threads. If this
//document could be used from other threads (e.g., the rendering thread inside
//PDFView/PDFViewCtrl, if used), it is good practice to lock it.
//Notice: don't forget to call doc.Unlock() to avoid deadlock.
doc.Lock();

txt_search.Begin( doc, pattern, mode );
while ( true )
{
           SearchResult result = code = txt_search.Run(page_num, result_str, ambient_string, hlts );
           if ( code == TextSearch::e_found )
           {
                   result_str.ConvertToAscii(buf, 32, true);
                   cout < "found one instance: " < char_buf < endl;
           }
           else
           {
                   break;
           }
}

//unlock the document to avoid deadlock.
doc.UnLock();

For a full sample, please take a look at the TextSearch sample project.

Begin(doc, pattern, mode, start_page=-1, end_page=-1)

Initialize for search process. This should be called before starting the actual search with method Run().

Parameters:

• doc (PDFDoc) – the PDF document to search in.

• pattern (string) – the pattern to search for. When regular expression is used, it contains the expression, and in verbatim mode, it is the exact string to search for.

• mode (int) – the mode of the search process.

• start_page (int) – the start page of the page range to search in. The default value is -1 indicating the range starts from the first page.

• end_page (int) – the end page of the page range to search in. The default value is -1 indicating the range ends at the last page.

Return type:

boolean

Returns:

true if the initialization has succeeded.

Destroy()

Frees the native memory of the object.

GetCurrentPage()

Retrieve the number of the current page that is searched in. If the returned value is -1, it indicates the search process has not been initialized (e.g., Begin() is not called yet); if the returned value is 0, it indicates the search process has finished, and if the returned value is positive, it is a valid page number.

Return type:

int

Returns:

the current page number.

GetMode()

Retrieve the current search mode.

Return type:

int

Returns:

the current search mode.

Run()

Search the document and returns upon the following circumstances: a)Reached the end of the document; b)Reached the end of a page (if set to return by specifying mode ‘e_page_stop’ ); c)Found an instance matching the search pattern.

Note that this method should be called in a loop in order to find all matching instances; in other words, the search is conducted in an incremental fashion.

SetAmbientLettersAfter(ambient_letters_after)

Sets the maximum number of ambient string letters after the search term (default: 70). This should be called before starting the actual search with method Run().

Parameters:

ambient_letters_after (int) – – maximum number of letters.

SetAmbientLettersBefore(ambient_letters_before)

Sets the maximum number of ambient string letters before the search term (default: 30). This should be called before starting the actual search with method Run().

Parameters:

ambient_letters_before (int) – – maximum number of letters.

SetAmbientWordsAfter(ambient_words_after)

Sets the maximum number of ambient string words after the search term (default: 10). This should be called before starting the actual search with method Run().

Parameters:

ambient_words_after (int) – – maximum number of words.

SetAmbientWordsBefore(ambient_words_before)

Sets the maximum number of ambient string words before the search term (default: 1). This should be called before starting the actual search with method Run().

Parameters:

ambient_words_before (int) – – maximum number of words.

SetMode(mode)

Set the current search mode. For example, the following code turns on the regular expressions:

TextSearch ts;

… TextSearch::Mode mode = ts.GetMode(); mode |= TextSearch::e_reg_expression; ts.SetMode(mode); …

Parameters:

mode (int) – the search mode to set.

SetOCGContext(context)

Sets the Optional Content Group (OCG) context that should be used when processing the document. This function can be used to change the current OCG context. Optional content (such as PDF layers) will be selectively processed based on the states of optional content groups in the given context.

Parameters:

context (Context) – Optional Content Group (OCG) context, or NULL if TextSearch should process all content on the page.

SetPattern(pattern)

Set the current search pattern. Note that it is not necessary to call this method since the search pattern is already set when calling the Begin() method. This method is provided for users to change the search pattern while searching through a document.

Parameters:

pattern (string) – the search pattern to set.

Return type:

boolean

Returns:

true if the setting has succeeded.

SetRightToLeftLanguage(flag)

Tells TextSearch that language is from right to left.

Parameters:

flag (boolean) – Set to true if the language is right to left.

e_ambient_string = 64

e_case_sensitive = 2

e_highlight = 32

e_page_stop = 16

e_raw_text_search = 128

e_reg_expression = 1

e_search_up = 8

e_search_using_zorder = 256

e_whole_word = 4

property mp_textsearch

property thisown

The membership flag

class apryse_sdk.TextSettings

Bases: object

A class that stores image text optimization settings.

EmbedFonts(embed)

Sets whether fonts should be embedded. This will generally increase the size of the file, but will make the file appear the same on different machines. Font embedding is off by default.

Parameters:

embed (boolean) – if true all fonts will be embedded.

SubsetFonts(subset)

Sets whether embedded fonts will be subset. This will generally reduce the size of fonts, but will strip font hinting. Subsetting is off by default.

Parameters:

subset (boolean) – if true all embedded fonts will be subsetted.

property thisown

The membership flag

class apryse_sdk.TextStyledElement(args, kwargs)

Bases: object

A TextStyledElement provides access to the text style properties of a ContentElement.

GetFontFace()

Get the font face name used for the style

Return type:

string

Returns:

the font face name used for the style

GetFontSize()

Get the font size of the style

Return type:

double

Returns:

The font size of the style

IsBold()

Get the bold setting of the style

Return type:

boolean

Returns:

true if the style is set as ‘Bold’

IsItalic()

Get the italic setting of the style

Return type:

boolean

Returns:

true if the style is set as ‘Italic’

SetBackgroundColor(red, green, blue)

Set the background color for the style

Parameters:

• red (int) – The red component of the text color

• green (int) – The green component of the text color

• blue (int) – The blue component of the text color

SetBold(val)

Set or unset the style as ‘Bold’

Parameters:

val (boolean) – use true to set the style as ‘Bold’

SetFontFace(font_name)

Set the font face name to be used for the style

Parameters:

font_name (string) – The font face name to use for the style

SetFontSize(font_size)

Set font size of the style

Parameters:

font_size (double) – The font size to use for the style

SetItalic(val)

Set or unset the style as ‘italic’

Parameters:

val (boolean) – use true to set the style as ‘Italic’

SetTextColor(red, green, blue)

Set text color for the style

Parameters:

• red (int) – The red component of the text color

• green (int) – The green component of the text color

• blue (int) – The blue component of the text color

property m_impl

property thisown

The membership flag

class apryse_sdk.TextWidget(args)

Bases: Widget

An object representing a Text Box used in a PDF Form.

static Create(args)

Overload 1:

Creates a new Text Widget annotation, in the specified document.

Parameters:

• doc (PDFDoc) – The document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds, specified in user space coordinates.

• field_name (string) – The name of the field for which to create a Text widget.

Return type:

TextWidget

Returns:

A newly created blank Text Widget annotation.

Overload 2:

Creates a new Text Widget annotation, in the specified document.

Parameters:

• doc (PDFDoc) – The document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds, specified in user space coordinates.

• field (Field) – the field for which to create a Text Widget.

Return type:

TextWidget

Returns:

A newly created blank Widget annotation.

GetText()

Retrieves the text content of the Text Widget.

Return type:

string

Returns:

The Text Widget contents.

SetText(text)

Sets the text content of the Text Widget.

Parameters:

text (string) – The text to be displayed in the Text Widget.

property thisown

The membership flag

apryse_sdk.TextWidget_Create(args)

Overload 1:

Creates a new Text Widget annotation, in the specified document.

Parameters:

• doc (PDFDoc) – The document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds, specified in user space coordinates.

• field_name (string) – The name of the field for which to create a Text widget.

Return type:

TextWidget

Returns:

A newly created blank Text Widget annotation.

Overload 2:

Creates a new Text Widget annotation, in the specified document.

Parameters:

• doc (PDFDoc) – The document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds, specified in user space coordinates.

• field (Field) – the field for which to create a Text Widget.

Return type:

TextWidget

Returns:

A newly created blank Widget annotation.

apryse_sdk.Text_Create(args)

Overload 1:

Creates a new Text annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds in default user space units.

Return type:

Text

Returns:

A newly created blank Text annotation.

Creates a new Text annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds in default user space units.

• contents (string) – The text of the annotation, that shall be displayed in its popup window.

Return type:

Text

Returns:

A newly created Text annotation.

Overload 2:

Creates a new Text annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Point) – A point specifying the annotation’s location in default user space units. This determines the location of bottom left corner of the annotation’s icon.

• contents (string) – The text of the annotation, that shall be displayed in its popup window.

Return type:

Text

Returns:

A newly created Text annotation.

Overload 3:

Creates a new Text annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Point) – A point specifying the annotation’s location in default user space units. This determines the location of bottom left corner of the annotation’s icon.

• contents – The text of the annotation, that shall be displayed in its popup window.

Return type:

Text

Returns:

A newly created Text annotation.

apryse_sdk.Text_CreateAnnot(args)

class apryse_sdk.TiffOutputOptions

Bases: object

A class containing options for ToTiff functions

SetAnnots(enable)

Enables or disables drawing of annotations.

This option is enabled by default.

SetBox(type)

Specifies the page box/region to rasterize. Possible values are media, crop, trim, bleed, and art. By default, page crop region will be rasterized.

SetCMYK(enable)

Render and export the image in CMYK mode. By default, the image is rendered and exported in RGB color space.

SetClip(x1, y1, x2, y2)

User definable clip box. By default, the clip region is identical to current page ‘box’.

SetDPI(dpi)

The output resolution, from 1 to 1000, in Dots Per Inch (DPI). The higher the DPI, the larger the image. Resolutions larger than 1000 DPI can be achieved by rendering image in tiles or stripes. The default resolution is 92 DPI.

SetDither(enable)

Enables dithering when the image is exported in palletized or monochrome mode.

This option is disabled by default.

SetGamma(gamma)

Sets the gamma factor used for anti-aliased rendering. Typical values are in the range from 0.1 to 3. Gamma correction can be used to improve the quality of anti-aliased image output and can (to some extent) decrease the appearance common anti-aliasing artifacts (such as pixel width lines between polygons). The default gamma is 0.

SetGray(enable)

Render and export the image in grayscale mode. Sets pixel format to 8 bits per pixel grayscale. By default, the image is rendered and exported in RGB color space.

SetHRes(hres)

Sets the width of the output image, in pixels.

SetMono(enable)

Export the rendered image as 1 bit per pixel (monochrome) image. The image will be compressed using G4 CCITT compression algorithm. By default, the image is not dithered. To enable dithering use ‘SetDither’ option. This option is disabled by default.

SetOverprint(mode)

Enable or disable support for overprint and overprint simulation. Overprint is a device dependent feature and the results will vary depending on the output color space and supported colorants (i.e. CMYK, CMYK+spot, RGB, etc). Default is e_op_pdfx_on.

Parameters:

op – e_op_on: always enabled; e_op_off: always disabled; e_op_pdfx_on: enabled for PDF/X files only.

SetPages(page_desc)

Specifies the list of pages to convert. “1” for only the first page. “1-5” for pages 1 to 5. “1, 5, 7” for pages 1, 5, and 7. “odd” for all odd pages. “even” for all even pages. By default, all pages are converted.

SetPalettized(enable)

Enabled the output of palettized TIFFs.

This option is disabled by default.

SetPrintmode(enable)

Renders annotations in the print mode. This option can be used to render ‘Print Only’ annotations and to hide ‘Screen Only’ annotations.

This option is disabled by default.

SetRotate(rotation)

Rotates all pages by a given number of degrees counterclockwise. The allowed values are 0, 90, 180, and 270. The default value is 0.

SetSmooth(enable)

Enables or disables image smoothing (default: enabled).

SetTransparentPage(enable)

Sets the page color to transparent. By default, Convert assumes that the page is drawn directly on an opaque white surface. Some applications may need to draw the page on a different backdrop. In this case any pixels that are not covered during rendering will be transparent.

This option is disabled by default.

SetVRes(vres)

Sets the height of the output image, in pixels.

property thisown

The membership flag

class apryse_sdk.TimestampingConfiguration(args)

Bases: object

A class representing a set of options for timestamping a document.

Destroy()

SetTimestampAuthorityServerPassword(in_password)

Setter for a password to use during timestamping.

Parameters:

in_password (string) – – a string representing a password.

SetTimestampAuthorityServerURL(in_url)

Setter to change the timestamp authority (TSA) URL to use during timestamping.

Parameters:

in_url (string) – – a string representing a URL of a timestamp authority.

SetTimestampAuthorityServerUsername(in_username)

Setter for a username to use during timestamping.

Parameters:

in_username (string) – – a string representing a username.

SetUseNonce(in_use_nonce)

Setter for whether to use a nonce (unique random number) during timestamping. This is on by default, and should be on whenever a timestamp authority supports it, because it helps prevent replay attacks.

Parameters:

in_use_nonce (boolean) – – a boolean value representing whether or not to use a nonce

TestConfiguration(in_opts)

Tests a timestamping configuration for usability and reports any failures. This function does not throw on many common failures, unlike the real signing, thereby allowing early diagnosis of things like connectivity issues with timestamp authorities.

Parameters:

in_opts (VerificationOptions) – – a set of verification options to try to use

Return type:

TimestampingResult

Returns:

A result object containing information about the status of the configuration test and any errors that occurred during it.

property m_impl

property thisown

The membership flag

class apryse_sdk.TimestampingResult(args)

Bases: object

A class representing the result of testing a timestamping configuration.

Destroy()

GetData()

If GetStatus gives true, returns the data from the completed timestamping operation, otherwise throws. If this result was returned from TimestampOnNextSave, then this data is the timestamp token. However, if this result was returned from GenerateContentsWithEmbeddedTimestamp, then this data is the main document CMS signature of the DigitalSignatureField but with a newly-added embedded timestamp (unsigned signature-time-stamp attribute as specified in PAdES and PDF 2.0).

Return type:

std::vector< UChar,std::allocator< UChar > >

Returns:

the data representing the result of the timestamping operation, if GetStatus gives true

GetResponseVerificationResult()

If a timestamp response was successfully retrieved from a timestamp authority, returns the result of verifying it. If a timestamp response was not received, throws. One should call HasResponseVerificationResult first to see if a detailed result is available before calling this function.

Return type:

EmbeddedTimestampVerificationResult

Returns:

a timestamp response verification result

GetStatus()

Retrieves the overall status of the timestamping configuration testing operation.

Return type:

boolean

Returns:

a boolean value representing the status.

GetString()

Retrieves a result message regarding the timestamping configuration testing operation.

Return type:

string

Returns:

a string result message.

Notes: Output may change in future versions.

HasResponseVerificationResult()

Returns whether a timestamp response verification result is available. This means that false will be returned when a timestamp response was not received or was empty (e.g. network failures, improper server configuration, bad URL, etc.). This function should be called to check for the availability of a verification result before actually attempting to retrieve one using GetResponseVerificationResult (which throws if a result is not available).

Return type:

boolean

Returns:

whether a timestamp response verification result is available

property m_impl

property thisown

The membership flag

class apryse_sdk.TrustVerificationResult(args)

Bases: object

The detailed result of a trust verification step of a verification operation performed on a digital signature.

Destroy()

GetCertPath()

Retrieves the certificate path that was used for verification.

Return type:

std::vector< Crypto::X509Certificate,std::allocator< Crypto::X509Certificate > >

Returns:

a container of X509Certificate objects

GetEmbeddedTimestampVerificationResult()

Returns the detailed timestamp result inside this TrustVerificationResult. One must call HasEmbeddedTimestampVerificationResult first to check whether the result is available.

Return type:

EmbeddedTimestampVerificationResult

Returns:

an EmbeddedTimestampVerificationResult object.

GetResultString()

Retrieves a string representation of the details of the trust verification status.

Return type:

string

Returns:

A string.

Notes: Output may change in future versions.

GetTimeOfTrustVerification()

Retrieves the reference-time used for trust verification as an epoch time.

Return type:

int

Returns:

An integral value representing an epoch time.

GetTimeOfTrustVerificationEnum()

Retrieves the type of reference-time used for trust verification.

Return type:

int

Returns:

An enumerated value representing the type of reference-time used for trust verification.

HasEmbeddedTimestampVerificationResult()

Returns whether this TrustVerificationResult has a detailed timestamp result inside.

Return type:

boolean

Returns:

a boolean value representing whether this TrustVerificationResult has a detailed timestamp result inside.

WasSuccessful()

Retrieves the trust verification status.

Return type:

boolean

Returns:

A boolean representing whether or not the trust verification operation was successful. Whether trust-related warnings are treated as errors or not depend on the VerificationOptions used for the verification operation.

property m_impl

property thisown

The membership flag

class apryse_sdk.UInt32Iterator(args)

Bases: object

Supports a simple iteration over a generic collection.

Current()

Note: HasNext() must be true before calling Current()

Return type:

int

Returns:

the current element in the collection

Destroy()

Frees the native memory of the object.

HasNext()

Return type:

boolean

Returns:

true if the iterator can be successfully advanced to the next element; false if the iterator is no longer valid.

Next()

Note: HasNext() must be true before calling Next() Advances the iterator to the next element of the collection.

property mp_impl

property thisown

The membership flag

class apryse_sdk.Underline(args)

Bases: TextMarkup

An Underline annotation shows as a line segment across the bottom of a word or a group of contiguous words.

static Create(doc, pos)

Creates a new Underline annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the Underline annotation is added.

• pos (Rect) – A rectangle specifying the Underline annotation’s bounds in default user space units.

Return type:

Underline

Returns:

A newly created blank Underline annotation.

static CreateAnnot(doc, pos)

property thisown

The membership flag

apryse_sdk.Underline_Create(doc, pos)

Creates a new Underline annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the Underline annotation is added.

• pos (Rect) – A rectangle specifying the Underline annotation’s bounds in default user space units.

Return type:

Underline

Returns:

A newly created blank Underline annotation.

apryse_sdk.Underline_CreateAnnot(doc, pos)

class apryse_sdk.UndoManager(args)

Bases: object

The class UndoManager. Undo-redo interface; one-to-one mapped to document

CanRedo()

Returns a boolean indicating whether it is possible to redo from the current snapshot.

Return type:

boolean

Returns:

A boolean indicating whether it is possible to redo from the current snapshot.

CanUndo()

Returns whether it is possible to undo from the current snapshot.

Return type:

boolean

Returns:

Whether it is possible to undo from the current snapshot.

Destroy()

DiscardAllSnapshots()

Forget all changes in this manager (without changing the document).

Return type:

DocSnapshot

Returns:

An invalid DocSnapshot.

GetNextRedoSnapshot()

Gets the next state of the document. This state may be invalid if it is impossible to redo.

Return type:

DocSnapshot

Returns:

The next state of the document. This state may be invalid if it is impossible to redo.

GetNextUndoSnapshot()

Gets the previous state of the document. This state may be invalid if it is impossible to undo.

Return type:

DocSnapshot

Returns:

The previous state of the document. This state may be invalid if it is impossible to undo.

Redo()

Restores to the next snapshot, if there is one.

Return type:

ResultSnapshot

Returns:

A representation of the transition to the next snapshot, if there is one.

TakeSnapshot()

Creates a snapshot of document state, transitions to the new snapshot.

Return type:

ResultSnapshot

Returns:

A representation of the transition.

Undo()

Restores to the previous snapshot point, if there is one.

Return type:

ResultSnapshot

Returns:

The resulting snapshot id.

property m_impl

property thisown

The membership flag

class apryse_sdk.VectorAnnot(args)

Bases: object

append(x)

assign(n, x)

back()

begin()

capacity()

clear()

empty()

end()

erase(args)

front()

get_allocator()

insert(args)

iterator()

pop()

pop_back()

push_back(x)

rbegin()

rend()

reserve(n)

resize(args)

size()

swap(v)

property thisown

The membership flag

class apryse_sdk.VectorByteRange(args)

Bases: object

append(x)

assign(n, x)

back()

begin()

capacity()

clear()

empty()

end()

erase(args)

front()

get_allocator()

insert(args)

iterator()

pop()

pop_back()

push_back(x)

rbegin()

rend()

reserve(n)

resize(args)

size()

swap(v)

property thisown

The membership flag

class apryse_sdk.VectorChar(args)

Bases: object

append(x)

assign(n, x)

back()

begin()

capacity()

clear()

empty()

end()

erase(args)

front()

get_allocator()

insert(args)

iterator()

pop()

pop_back()

push_back(x)

rbegin()

rend()

reserve(n)

resize(args)

size()

swap(v)

property thisown

The membership flag

class apryse_sdk.VectorDisallowedChange(args)

Bases: object

append(x)

assign(n, x)

back()

begin()

capacity()

clear()

empty()

end()

erase(args)

front()

get_allocator()

insert(args)

iterator()

pop()

pop_back()

push_back(x)

rbegin()

rend()

reserve(n)

resize(args)

size()

swap(v)

property thisown

The membership flag

class apryse_sdk.VectorDouble(args)

Bases: object

append(x)

assign(n, x)

back()

begin()

capacity()

clear()

empty()

end()

erase(args)

front()

get_allocator()

insert(args)

iterator()

pop()

pop_back()

push_back(x)

rbegin()

rend()

reserve(n)

resize(args)

size()

swap(v)

property thisown

The membership flag

class apryse_sdk.VectorInt(args)

Bases: object

append(x)

assign(n, x)

back()

begin()

capacity()

clear()

empty()

end()

erase(args)

front()

get_allocator()

insert(args)

iterator()

pop()

pop_back()

push_back(x)

rbegin()

rend()

reserve(n)

resize(args)

size()

swap(v)

property thisown

The membership flag

class apryse_sdk.VectorObj(args)

Bases: object

append(x)

assign(n, x)

back()

begin()

capacity()

clear()

empty()

end()

erase(args)

front()

get_allocator()

insert(args)

iterator()

pop()

pop_back()

push_back(x)

rbegin()

rend()

reserve(n)

resize(args)

size()

swap(v)

property thisown

The membership flag

class apryse_sdk.VectorPage(args)

Bases: object

append(x)

assign(n, x)

back()

begin()

capacity()

clear()

empty()

end()

erase(args)

front()

get_allocator()

insert(args)

iterator()

pop()

pop_back()

push_back(x)

rbegin()

rend()

reserve(n)

resize(args)

size()

swap(v)

property thisown

The membership flag

class apryse_sdk.VectorQuadPoint(args)

Bases: object

append(x)

assign(n, x)

back()

begin()

capacity()

clear()

empty()

end()

erase(args)

front()

get_allocator()

insert(args)

iterator()

pop()

pop_back()

push_back(x)

rbegin()

rend()

reserve(n)

resize(args)

size()

swap(v)

property thisown

The membership flag

class apryse_sdk.VectorRedaction(args)

Bases: object

append(x)

assign(n, x)

back()

begin()

capacity()

clear()

empty()

end()

erase(args)

front()

get_allocator()

insert(args)

iterator()

pop()

pop_back()

push_back(x)

rbegin()

rend()

reserve(n)

resize(args)

size()

swap(v)

property thisown

The membership flag

class apryse_sdk.VectorSeparation(args)

Bases: object

append(x)

assign(n, x)

back()

begin()

capacity()

clear()

empty()

end()

erase(args)

front()

get_allocator()

insert(args)

iterator()

pop()

pop_back()

push_back(x)

rbegin()

rend()

reserve(n)

resize(args)

size()

swap(v)

property thisown

The membership flag

class apryse_sdk.VectorString(args)

Bases: object

append(x)

assign(n, x)

back()

begin()

capacity()

clear()

empty()

end()

erase(args)

front()

get_allocator()

insert(args)

iterator()

pop()

pop_back()

push_back(x)

rbegin()

rend()

reserve(n)

resize(args)

size()

swap(v)

property thisown

The membership flag

class apryse_sdk.VectorUChar(args)

Bases: object

append(x)

assign(n, x)

back()

begin()

capacity()

clear()

empty()

end()

erase(args)

front()

get_allocator()

insert(args)

iterator()

pop()

pop_back()

push_back(x)

rbegin()

rend()

reserve(n)

resize(args)

size()

swap(v)

property thisown

The membership flag

class apryse_sdk.VectorVectorX509Certificate(args)

Bases: object

append(x)

assign(n, x)

back()

begin()

capacity()

clear()

empty()

end()

erase(args)

front()

get_allocator()

insert(args)

iterator()

pop()

pop_back()

push_back(x)

rbegin()

rend()

reserve(n)

resize(args)

size()

swap(v)

property thisown

The membership flag

class apryse_sdk.VectorX501AttributeTypeAndValue(args)

Bases: object

append(x)

assign(n, x)

back()

begin()

capacity()

clear()

empty()

end()

erase(args)

front()

get_allocator()

insert(args)

iterator()

pop()

pop_back()

push_back(x)

rbegin()

rend()

reserve(n)

resize(args)

size()

swap(v)

property thisown

The membership flag

class apryse_sdk.VectorX509Certificate(args)

Bases: object

append(x)

assign(n, x)

back()

begin()

capacity()

clear()

empty()

end()

erase(args)

front()

get_allocator()

insert(args)

iterator()

pop()

pop_back()

push_back(x)

rbegin()

rend()

reserve(n)

resize(args)

size()

swap(v)

property thisown

The membership flag

class apryse_sdk.VectorX509Extension(args)

Bases: object

append(x)

assign(n, x)

back()

begin()

capacity()

clear()

empty()

end()

erase(args)

front()

get_allocator()

insert(args)

iterator()

pop()

pop_back()

push_back(x)

rbegin()

rend()

reserve(n)

resize(args)

size()

swap(v)

property thisown

The membership flag

class apryse_sdk.VerificationOptions(args)

Bases: object

Options pertaining to digital signature verification.

AddTrustedCertificate(args)

Overload 1:

Adds a certificate to the store of trusted certificates inside this options object.

Parameters:

• in_certificate_buf (UChar) – – a buffer consisting of the data of an X.509 public-key certificate encoded in binary DER (Distinguished Encoding Rules) format, or in PEM (appropriate Privacy-Enhanced Mail header+Base64 encoded DER+appropriate footer) format

• in_buf_size (int) – – buffer size

• in_trust_flags (int) – – a combination of trust flags (see enum CertificateTrustFlag) that determine for which situations this certificate should be trusted during trust verification. There is a default parameter value, the e_default_trust CertificateTrustFlag, which matches Acrobat’s behaviour for this parameter.

Overload 2:

Adds a certificate to the store of trusted certificates inside this options object, by loading it from a file.

Parameters:

• in_filepath (string) – – a path to a file containing the data of an X.509 public-key certificate encoded in binary DER (Distinguished Encoding Rules) format, or in PEM (appropriate Privacy-Enhanced Mail header+Base64 encoded DER+appropriate footer) format.

• in_trust_flags (int) – – a combination of trust flags (see enum CertificateTrustFlag) that determine for which situations this certificate should be trusted during trust verification. There is a default parameter value, the e_default_trust CertificateTrustFlag, which matches Acrobat’s behaviour for this parameter.

Overload 3:

Adds a certificate to the store of trusted certificates inside this options object, by loading it from a file.

Parameters:

• in_filepath (string) – – a path to a file containing the data of an X.509 public-key certificate encoded in binary DER (Distinguished Encoding Rules) format, or in PEM (appropriate Privacy-Enhanced Mail header+Base64 encoded DER+appropriate footer) format.

• in_trust_flags – – a combination of trust flags (see enum CertificateTrustFlag) that determine for which situations this certificate should be trusted during trust verification. There is a default parameter value, the e_default_trust CertificateTrustFlag, which matches Acrobat’s behaviour for this parameter.

AddTrustedCertificates(in_P7C_binary_DER_certificates_file_data, in_size)

Bulk trust list loading API from P7C. Attempts to decode the input data as binary DER and trust multiple trusted root certificates from it. Compatible with Acrobat’s .P7C format, which is a variation on PKCS #7/CMS that only contains certificates (i.e. no CRLs, no signature, etc.). If a certificate cannot be decoded, this is ignored and an attempt is made to decode the next certificate. This overload takes no account of trust-level flags because none are available in the P7C format. Therefore, when this function is used, all certificates in the P7C file will be loaded as if trusted for everything, which may lead to false positives when compared to other PDF software. (Most applications use the FDF Cert Exchange format.) The FDF-trust-list-loading function “LoadTrustList” should be used instead whenever possible.

Parameters:

• in_P7C_binary_DER_certificates_file_data (UChar) – – the P7C-format bulk certificate data, encoded in binary DER (Distinguished Encoding Rules)

• in_size (int) – – the size of the data, in bytes

Destroy()

EnableDigestVerification(in_on_or_off)

Sets a flag that can turn on or off the verification of the digest (cryptographic hash) component of a digital signature.

Parameters:

in_on_or_off (boolean) – – A boolean.

EnableModificationVerification(in_on_or_off)

Sets a flag that can turn on or off the verification of the permissibility of any modifications made to the document after the signing of the digital signature being verified, in terms of the document and field permissions specified by the digital signature being verified.

Parameters:

in_on_or_off (boolean) – – A boolean.

EnableOnlineCRLRevocationChecking(in_on_or_off)

Enables/disables online CRL revocation checking. The default setting is for it to be turned off, but this may change in future versions.

Notes: CRL checking is off by default because the technology is inherently complicated and resource-intensive, but may help improve verification rate when files are verified against a recent reference-time (e.g. maximum security mode), because online CRLs will be valid within that time. This mode will not be useful for old archival-type (‘LTV’) documents verified in archiving-and-compatibility security mode, because their online OCSP and/or CRL responder servers may not be alive anymore. However, such LTV documents can be created (if the CRL responder servers are still active) by enabling online checking, verifying, and then embedding the data using DigitalSignatureField.EnableLTVOfflineVerification.

Parameters:

in_on_or_off (boolean) – – what setting to use

EnableOnlineOCSPRevocationChecking(in_on_or_off)

Enables/disables online OCSP revocation checking. The default setting is for it to be turned on.

Parameters:

in_on_or_off (boolean) – – what setting to use.

EnableOnlineRevocationChecking(in_on_or_off)

Enables/disables all online revocation checking modes. The default settings are that online OCSP is turned on and online CRL is turned off, but the default CRL setting may change in future versions.

Notes: CRL checking is off by default because the technology is inherently complicated

and resource-intensive, but may help improve verification rate when files are verified against a recent reference-time (e.g. maximum security mode), because online CRLs will be valid within that time. This mode will not be useful for old archival-type (‘LTV’) documents verified in archiving-and-compatibility security mode, because their online OCSP and/or CRL responder servers may not be alive anymore. However, such LTV documents can be created (if the CRL responder servers are still active) by enabling online checking, verifying, and then embedding the data using DigitalSignatureField.EnableLTVOfflineVerification.

Parameters:

in_on_or_off (boolean) – – what setting to use

EnableTrustVerification(in_on_or_off)

Sets a flag that can turn on or off the verification of the trust status of a digital signature.

Parameters:

in_on_or_off (boolean) – – A boolean.

GetTrustedCertificate(index)

Get the certificate at a specific position in the current list of trusted certificates.

Parameters:

index (int) – – the index of the certificate in the current list.

Return type:

X509Certificate

Returns:

the certificate at position index in the list.

GetTrustedCertificateCount()

Get the number of trusted certificates that have been added.

Return type:

int

Returns:

the number of trusted certificates.

LoadTrustList(in_fdf_cert_exchange_data)

Bulk trust list loading API with trust flag support. Loads a trust list that is structured in Acrobat’s FDF Data/Cert Exchange format into the VerificationOptions certificate store. Use of this function is strongly recommended instead of the P7C API (i.e. AddTrustedCertificates). Certificates inside the FDF trust list that cannot be decoded and loaded, will be skipped.

Parameters:

in_fdf_cert_exchange_data (FDFDoc) – – an FDFDoc from the FDF cert exchange data

SetRevocationTimeout(in_revocation_timeout_milliseconds)

Sets the timeout for online revocation requests.

Parameters:

in_revocation_timeout_milliseconds (int) – The timeout value in milliseconds.

e_certification_trust = 2

e_compatibility_and_archiving = 0

e_complete_trust = 119

e_current = 2

e_default_trust = 97

e_dynamic_content = 4

e_identity = 32

e_javascript = 16

e_maximum = 1

e_signing = 0

e_signing_trust = 1

e_timestamp = 1

e_trust_anchor = 64

property m_impl

property thisown

The membership flag

class apryse_sdk.VerificationResult(args)

Bases: object

The result of a verification operation performed on a digital signature.

Destroy()

GetDigestAlgorithm()

Retrieves an enumeration value representing the digest algorithm used to sign the signature that is associated with this verification result. For DocTimeStamp signatures, returns the weakest algorithm found (between the CMS and message imprint digests).

Return type:

int

Returns:

A DigestAlgorithm enumeration value.

GetDigestStatus()

Retrieves the digest-related result condition associated with a digital signature verification operation.

Return type:

int

Returns:

A DigestStatus-type enumeration value.

GetDigestStatusAsString()

Retrieves the digest-related result condition associated with a digital signature verification operation, as a descriptive string.

Return type:

string

Returns:

a string.

GetDisallowedChanges()

Retrieves a list of informational structures regarding any disallowed changes that have been made to the document since the signature associated with this verification result was signed.

Return type:

std::vector< PDF::VerificationResult::DisallowedChange,std::allocator< PDF::VerificationResult::DisallowedChange > >

Returns:

a collection of DisallowedChange objects.

GetDocumentStatus()

Retrieves the document-related result condition associated with a digital signature verification operation.

Return type:

int

Returns:

A DocumentStatus-type enumeration value.

GetDocumentStatusAsString()

Retrieves the document-related result condition associated with a digital signature verification operation, as a descriptive string.

Return type:

string

Returns:

a string.

GetPermissionsStatus()

Retrieves the result condition about permissions checks performed on any unsigned modifications associated with a digital signature verification operation.

Return type:

int

Returns:

A ModificationPermissionsStatus-type enumeration value.

GetPermissionsStatusAsString()

Retrieves the result condition about permissions checks performed on any unsigned modifications associated with a digital signature verification operation, as a descriptive string.

Return type:

string

Returns:

a string.

GetTrustStatus()

Retrieves the trust-related result condition associated with a digital signature verification operation.

Return type:

int

Returns:

A TrustStatus-type enumeration value.

GetTrustStatusAsString()

Retrieves the trust-related result condition associated with a digital signature verification operation, as a descriptive string.

Return type:

string

Returns:

a string.

GetTrustVerificationResult()

Retrieves the detailed result associated with the trust step of the verification operation that returned this VerificationResult, if such a detailed trust result is available. Must call HasTrustVerificationResult first and check for a true result.

Return type:

TrustVerificationResult

Returns:

a TrustVerificationResult object

Notes: This function will throw if no TrustVerificationResult is available.

GetUnsupportedFeatures()

Retrieves reports about unsupported features encountered during verification. This function is the canonical source of information about all unsupported features encountered. Current possible values:

“unsupported signature encoding”, “usage rights signature”, “legal content attestations”, “unsupported digest algorithm”

Return type:

std::vector< std::string,std::allocator< std::string > >

Returns:

a container of strings representing unsupported features encountered during verification

Notes: Output may change in future versions.

GetVerificationStatus()

Retrieves the main verification status. The main status is determined based on the other statuses. Verification may fail for many reasons; some of these reasons are the presence of features that are not supported yet. It may be desirable for you to report unsupported signatures differently (for example, using a question mark rather than an X mark). Any unsupported features encountered can be retrieved by the use of the function GetUnsupportedFeatures on this class.

Return type:

boolean

Returns:

A boolean representing whether or not the verification operation was completely successful.

HasTrustVerificationResult()

Returns whether there is a detailed TrustVerificationResult in this VerificationResult or not.

Return type:

boolean

Returns:

A boolean.

e_bad_byteranges = 3

e_corrupt_cryptographic_contents = 4

e_corrupt_file = 1

e_digest_invalid = 0

e_digest_verification_disabled = 2

e_digest_verified = 1

e_has_allowed_changes = 1

e_invalidated_by_disallowed_changes = 0

e_no_digest_status = 4

e_no_error = 0

e_no_permissions_status = 4

e_no_trust_status = 3

e_permissions_verification_disabled = 3

e_trust_verification_disabled = 2

e_trust_verified = 0

e_unmodified = 2

e_unsigned = 2

e_unsupported_digest_algorithm = 6

e_unsupported_encoding = 5

e_unsupported_permissions_features = 5

e_unsupported_trust_features = 4

e_untrusted = 1

e_weak_digest_algorithm_but_digest_verifiable = 3

property m_impl

property thisown

The membership flag

class apryse_sdk.ViewChangeCollection(args)

Bases: object

static CreateInternal(impl)

Destroy()

GetHandleInternal()

property mp_collection

property thisown

The membership flag

apryse_sdk.ViewChangeCollection_CreateInternal(impl)

class apryse_sdk.ViewerOptimizedOptions

Bases: object

SetMinimumInitialThumbnails(initial_thumbs)

Set the number of pages starting from the first for which to guarantee thumbnails regardless of page complexity. This can help improve the viewing experience on the first few pages without increasing the file size dramatically. If this number is greater than the number of pages in the document all of the pages will have thumbnails.

Parameters:

initial_thumbs (int) – The number of pages starting with the first which are guaranteed to have thumbnails. The default value is 1, which means only the first page is guaranteed to have a thumbnail.

SetOverprint(mode)

Enable or disable support for overprint and overprint simulation in generated thumbnails. Overprint is a device dependent feature and the results will vary depending on the output color space and supported colorants (i.e. CMYK, CMYK+spot, RGB, etc). Default is e_op_pdfx_on.

Parameters:

mode (int) – e_op_on: always enabled; e_op_off: always disabled; e_op_pdfx_on: enabled for PDF/X files only.

SetThumbnailRenderingThreshold(threshold)

For any pages that are not forced to include thumbnails this function adjusts whether we should include them depending on the complexity of the page. This can be used to include fewer or more thumbnails as required by the use case. In particular reducing this value will tend to increase the number of page thumbnails included and vice versa.

Parameters:

threshold (int) – A number from 0 (include all thumbnails) to 100 (include only the first thumbnail) representing the complexity at which SaveViewerOptimized would include the thumbnail. The default value is 50.

SetThumbnailSize(size)

The maximum allowed length for the thumbnail’s height/width. The default thumbnail size is 1024.

Parameters:

size (int) – the maximum dimension (width or height) that thumbnails will have.

property m_obj

property m_objset

property thisown

The membership flag

class apryse_sdk.Watermark(args)

Bases: Annot

A Watermark annotation is an annotation that is printed at a fixed size and position on a page, regardless of the dimensions of the printed page.

static Create(doc, pos)

Creates a new Watermark annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds in default user space units.

Return type:

Watermark

Returns:

A newly created blank Watermark annotation.

static CreateAnnot(doc, pos)

property thisown

The membership flag

apryse_sdk.Watermark_Create(doc, pos)

Creates a new Watermark annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds in default user space units.

Return type:

Watermark

Returns:

A newly created blank Watermark annotation.

apryse_sdk.Watermark_CreateAnnot(doc, pos)

class apryse_sdk.WebFontDownloader

Bases: object

The class WebFontDownloader. static interface to control the behaviour of PDFNet web font downloading

static ClearCache()

clear any pre-cached font files residing in persistent storage.

static DisableDownloads()

Prevent PDFNet from accessing the network to download missing fonts. It may still use previously downloaded fonts (which are cached on disk).

static EnableDownloads()

Allow PDFNet to access the network to download missing fonts when possible.

static IsAvailable()

Find out whether the web font downloader is available in version of PDFNet.

Return type:

boolean

Returns:

returns true if web font downloading can be done.

static PreCacheAsync()

download and cache a base collection of fonts in a background thread. Will not do anything if downloading is currently disabled.

static SetCustomWebFontURL(url)

Set the root path into which the web font downloader will make requests.

Parameters:

url (string) – – The root path into which the web font downloader will make requests.

property thisown

The membership flag

apryse_sdk.WebFontDownloader_ClearCache()

clear any pre-cached font files residing in persistent storage.

apryse_sdk.WebFontDownloader_DisableDownloads()

Prevent PDFNet from accessing the network to download missing fonts. It may still use previously downloaded fonts (which are cached on disk).

apryse_sdk.WebFontDownloader_EnableDownloads()

Allow PDFNet to access the network to download missing fonts when possible.

apryse_sdk.WebFontDownloader_IsAvailable()

Find out whether the web font downloader is available in version of PDFNet.

Return type:

boolean

Returns:

returns true if web font downloading can be done.

apryse_sdk.WebFontDownloader_PreCacheAsync()

download and cache a base collection of fonts in a background thread. Will not do anything if downloading is currently disabled.

apryse_sdk.WebFontDownloader_SetCustomWebFontURL(url)

Set the root path into which the web font downloader will make requests.

Parameters:

url (string) – – The root path into which the web font downloader will make requests.

class apryse_sdk.WebPageSettings

Bases: object

Settings that control how a web page is opened and converted to PDF.

Destroy()

Frees the native memory of the object.

SetAllowJavaScript(enable)

Allow javascript from this web page to be run.

Parameters:

enable (boolean) –

• If true javascript’s are allowed.

Notes: This option is deprecated in the latest HTML2PDF module and may have no effect.

SetAllowPlugins(enable)

Allow Netscape and flash plugins from this web page to be run. Enabling will have limited success.

Parameters:

enable (boolean) –

• If true Netscape flash plugins will be run.

Notes: This option is deprecated in the latest HTML2PDF module and may have no effect.

SetBlockLocalFileAccess(block)

Allow local and piped files access to other local files. By default local file access is blocked due to security concerns.

Parameters:

block (boolean) –

• If true local files will be inaccessible. If false they will be be accessible which should only be used if the html is trusted.

SetConvertDelay(msec)

Amount of time to wait before starting to convert html to pdf. Converter will wait msec milliseconds before calling convert.

Parameters:

msec (int) –

• Time to wait in milliseconds, e.g. 1200.

SetDebugJavaScriptOutput(forward)

Forward javascript warnings and errors to output.

Parameters:

forward (boolean) –

• If true javascript errors and warnings will be forwarded

to stdout and the log.

Notes: This option is deprecated in the latest HTML2PDF module and may have no effect.

SetDefaultEncoding(encoding)

Default encoding to be used when not specified by the web page.

Parameters:

encoding (string) –

• Default encoding, e.g. utf-8 or iso-8859-1.

Notes: available encodings are Apple Roman, Big5, Big5-HKSCS, CP949, EUC-JP, EUC-KR, GB18030-0, IBM 850, IBM 866, IBM 874, ISO 2022-JP, ISO 8859-1 to 10, ISO 8859-13 to 16, Iscii-Bng, Dev, Gjr, Knd, Mlm, Ori, Pnj, Tlg, Tml, JIS X 0201, JIS X 0208, KOI8-R, KOI8-U, MuleLao-1, ROMAN8, Shift-JIS, TIS-620, TSCII, UTF-8, UTF-16, UTF-16BE, UTF-16LE, UTF-32, UTF-32BE, UTF-32LE, Windows-1250 to 1258, WINSAMI2. This option is deprecated in the latest HTML2PDF module and may have no effect.

SetExternalLinks(convert)

Convert external links in HTML document to external PDF links.

Parameters:

convert (boolean) –

• If true PDF pages produced from this web page

can have external links.

Notes: This option is deprecated in the latest HTML2PDF module and may have no effect.

SetIncludeInOutline(include)

Add sections from this web page to the outline and table of contents.

Parameters:

include (boolean) –

• If true PDF pages created from this web

page will show up in the outline, and table of contents, otherwise, produced PDF pages will be excluded.

Notes: This option is deprecated in the latest HTML2PDF module and may have no effect.

SetInternalLinks(convert)

Convert internal links in HTML document into PDF references.

Parameters:

convert (boolean) –

• If true PDF pages produced from this web page

will have links to other PDF pages.

Notes: This option is deprecated in the latest HTML2PDF module and may have no effect.

SetJavaScriptDelay(msec)

Amount of time to wait for a web page to start printing after it’s completed loading. Converter will wait a maximum of msec milliseconds for javascript to call window.print().

Parameters:

msec (int) –

• Maximum wait time in milliseconds, e.g. 1200.

SetLoadErrorHandling(type)

SetLoadImages(load)

Print the images of this web page.

Parameters:

load (boolean) –

• If true images are printed.

Notes: This option is deprecated in the latest HTML2PDF module and may have no effect.

SetMinimumFontSize(size)

Set the smallest font size allowed, e.g 9.

Parameters:

size (int) –

• No fonts will appear smaller than this.

Notes: This option is deprecated in the latest HTML2PDF module and may have no effect.

SetPassword(password)

HTTP authentication password to use when logging into the website.

Parameters:

password (string) –

• The login password to use with the server, e.g. “elbarto”.

SetPrintBackground(background)

Print the background of this web page.

Parameters:

background (boolean) –

• If true background is printed.

SetPrintMediaType(_print)

Controls how content will be printed from this web page.

Parameters:

print (boolean) –

• If true the print media type will be used, otherwise

the screen media type will be used to print content.

Notes: This option is deprecated in the latest HTML2PDF module and may have no effect.

SetProduceForms(forms)

Turn HTML forms into PDF forms.

Parameters:

forms (boolean) –

• If true PDF pages produced from this web page

will have PDF forms for any HTML forms the web page has.

Notes: This option is deprecated in the latest HTML2PDF module and may have no effect.

SetProxy(proxy)

Use this proxy to load content from this web page.

Parameters:

proxy (Proxy) –

• Contains settings for proxy

SetSmartShrinking(enable)

Allow intelligent shrinking to fit more content per page.

Parameters:

enable (boolean) –

• If true intelligent shrinking is enabled and

the pixel/dpi ratio is nonant.

Notes: This option is deprecated in the latest HTML2PDF module and may have no effect.

SetStopSlowScripts(stop)

Stop slow running javascript’s.

Parameters:

stop (boolean) –

• If true, slow running javascript’s will be stopped.

Notes: This option is deprecated in the latest HTML2PDF module and may have no effect.

SetTimeout(msec)

Amount of time to wait in milliseconds for the entire converting and printing process. If conversion doesn’t finish before the timeout, it will be cancelled and no output is expected. Default 120,000 ms.

Parameters:

msec (int) – – Maximum timeout in milliseconds.

SetUserStyleSheet(url)

Url or path to user specified style sheet.

Parameters:

url (string) –

• URL or file path to user style sheet to be used

with this web page.

Notes: This option is deprecated in the latest HTML2PDF module and may have no effect.

SetUsername(username)

HTTP authentication username to use when logging into the website.

Parameters:

username (string) –

• The login name to use with the server, e.g. “bart”.

SetZoom(zoom)

Zoom factor to use when loading object.

Parameters:

zoom (double) –

• How much to magnify the web content by, e.g. 2.2.

e_abort = 0

e_ignore = 2

e_skip = 1

property mp_impl

property thisown

The membership flag

class apryse_sdk.Widget(args)

Bases: Annot

Interactive forms use widget annotations (PDF 1.2) to represent the appearance of fields and to manage user interactions. As a convenience, when a field has only a single associated widget annotation, the contents of the field dictionary and the annotation dictionary may be merged into a single dictionary containing entries that pertain to both a field and an annotation. NOTE This presents no ambiguity, since the contents of the two kinds of dictionaries do not conflict.

static Create(doc, pos, field)

Creates a new widget annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds in default user space units.

• field (Field) – A form field associated with this widget.

Return type:

Widget

Returns:

A newly created blank widget annotation.

GetAction()

Returns the action of the widget annotation

Return type:

Action

Returns:

An action object representing the action of the widget annotation that should be performed when the annotation is activated.

GetBackgroundColor()

Returns the background color of the annotation.

Return type:

ColorPt

Returns:

A color object that denotes the color of the Screen background.

Notes: The color can be in different color spaces: Gray, RGB, or CMYK. Call “GetBackgroundColorCompNum” to access the color space information corresponding to the border color.

GetBackgroundColorCompNum()

Returns the number indicating background color space of the annotation.

Return type:

int

Returns:

An integer indicating a color space value from the ColorSpace::Type enum. That is, 1 corresponding to “e_device_gray”, 3 corresponding to “e_device_rgb”, and 4 corresponding to “e_device_cmyk” if color space is applicable, 0 means no background color was assigned.

GetBorderColor()

Returns the border color of the annotation.

Return type:

ColorPt

Returns:

A color object that denotes the color of the Screen border.

Notes: The color can be in different color spaces: Gray, RGB, or CMYK. Call “GetBorderColorCompNum” to access the color space information corresponding to the border color.

GetBorderColorCompNum()

Returns the number indicating border color space of the annotation.

Return type:

int

Returns:

An integer indicating a color space value from the ColorSpace::Type enum. That is, 1 corresponding to “e_device_gray”, 3 corresponding to “e_device_rgb”, and 4 corresponding to “e_device_cmyk”. 0 means this annotation had no color assigned.

GetField()

Returns the field associated with the Widget.

Return type:

Field

Returns:

A Field object.

GetFitFull()

Returns the “fit full” flag.

Return type:

boolean

Returns:

A boolean value indicating the “fit full” flag value.

Notes: the fit full flag, if true, indicates that the button appearance shall be scaled to fit fully within the bounds of the annotation without taking into consideration the line width of the border. Default value: false.

GetFont()

Retrieves the font used for displaying text in this Widget.

Return type:

Font

Returns:

the font used by this Widget.

GetFontSize()

Returns the font size used in this Widget Annotation.

Return type:

double

Returns:

the font size

Notes: A font size of 0 specifies that the text should be autosized to fit in the Widget.

GetHIconLeftOver()

Returns the horizontal leftover space of the icon within the annotation.

Return type:

double

Returns:

A number indicating the horizontal leftover space of the icon within the annotation.

Notes: the horizontal leftover is a number that shall be between 0.0 and 1.0 indicating the fraction of leftover space to allocate at the left. A value of 0.0 shall position the icon at the left of the annotation rectangle. A value of 0.5 shall center it in the horizontal direction within the rectangle. This entry shall be used only if the icon is scaled proportionally. Default value: 0.5.

GetHighlightingMode()

Return type:

int

Returns:

the HighlightingMode of the widget annotation.

Notes: The annotation’s highlighting mode is the visual effect that shall be used when the mouse button is pressed or held down inside its active area A highlighting mode other than e_push will override any down appearance defined for the annotation. e_invert.

GetIconCaptionRelation()

Returns the Icon and caption relationship of the annotation.

Return type:

int

Returns:

A value of the “IconCaptionRelation” enum type. Default value: e_NoIcon.

See also: IconCaptionRelation

GetMouseDownCaptionText()

Returns the button down caption text of the annotation.

Return type:

string

Returns:

A string containing the button down text of the annotation.

Notes: The button down caption shall be displayed when the mouse button is pressed within its active area.

GetMouseDownIcon()

Returns the Mouse Down icon associated with the annotation.

Return type:

Obj

Returns:

An SDF object that represents the Mouse Down icon associated with the annotation.

Notes: The Mouse Down icon object is a form XObject defining the annotation’s alternate (down) icon, which shall be displayed when the mouse button is pressed within its active area.

GetRolloverCaptionText()

Returns the rollover caption text of the annotation.

Return type:

string

Returns:

A string containing the rollover caption text of the annotation.

Notes: The rollover caption shall be displayed when the user rolls the cursor into its active area without pressing the mouse button.

GetRolloverIcon()

Returns the rollover icon associated with the annotation.

Return type:

Obj

Returns:

An SDF object that represents the rollover icon associated with the annotation.

Notes: The rollover icon object is a form XObject defining the annotation’s rollover icon, which shall be displayed when the user rolls the cursor into its active area without pressing the mouse button.

GetScaleCondition()

Returns the condition under which the icon should be scaled.

Return type:

int

Returns:

A value of the “ScaleCondition” enum type. Default value: e_Always.

See also: ScaleCondition

GetScaleType()

Returns the Scale Type of the annotation.

Return type:

int

Returns:

A value of the “ScaleType” enum which represents the Scale Type of the annotation. Default value: P.

See also: ScaleType

GetStaticCaptionText()

Returns static caption text of the annotation.

Return type:

string

Returns:

A string containing the static caption text of the annotation.

Notes: The static caption is the annotation’s normal caption, which shall be displayed when it is not interacting with the user. Unlike the remaining entries with the captions, which apply only to widget annotations associated with pushbutton fields, the Static Caption(CA) entry may be used with any type of button field, including check boxes. This property is part of the Widget appearance characteristics dictionary, this dictionary that shall be used inructing a dynamic appearance stream specifying the annotation’s visual presentation on the page.

GetStaticIcon()

Returns the static icon associated with the annotation.

Return type:

Obj

Returns:

An SDF object that represents the static icon associated with the annotation.

Notes: The static icon object is a form XObject defining the annotation’s normal icon, which shall be displayed when it is not interacting with the user.

GetTextColor()

Returns the text color of the Widget Annotation.

Return type:

ColorPt

Returns:

the text color.

Notes: the color can be in different color spaces: Gray, RGB, or CMYK. Call “GetTextColorCompNum” to access the color space information corresponding to the border color.

GetTextColorCompNum()

Returns the number of color components in the text color of the Widget Annotation.

Return type:

int

Returns:

An integer indicating a color space value from the ColorSpace::Type enum. That is, 1 corresponding to “e_device_gray”, 3 corresponding to “e_device_rgb”, and 4 corresponding to “e_device_cmyk” if color space is applicable.

GetVIconLeftOver()

Returns the vertical leftover space of the icon within the annotation.

Return type:

double

Returns:

a number indicating the vertical leftover space of the icon within the annotation.

Notes: the vertical leftover space is a number that shall be between 0.0 and 1.0 indicating the fraction of leftover space to allocate at the bottom of the icon. A value of 0.0 shall position the icon at the bottom of the annotation rectangle. A value of 0.5 shall center it in the vertical direction within the rectangle. This entry shall be used only if the icon is scaled proportionally. Default value: 0.5.

SetAction(action)

Sets the action of the widget annotation (Optional; PDF 1.2 )

Parameters:

action (Action) – An action object representing the action of the widget annotation that should be performed when the annotation is activated.

SetBackgroundColor(c, compnum)

Sets the background color of the annotation. (Optional)

Parameters:

• col – A color point that denotes the color of the screen background.

• compnum (int) – An integer which value indicates the color space used for the parameter c.

SetBorderColor(col, compnum)

Sets the border color of the annotation. (Optional)

Parameters:

• col (ColorPt) – A color object that denotes the color of the screen border.

• compnum (int) – An integer which value indicates the color space used for the parameter c.

SetFitFull(ff)

Sets the “fit full” flag. (Optional)

Parameters:

ff (boolean) – A boolean value indicating the “fit full” flag value.

Notes: the fit full flag, if true, indicates that the button appearance shall be scaled to fit fully within the bounds of the annotation without taking into consideration the line width of the border. Default value: false.

SetFont(font)

Specifies a font to be used for text in this Widget.

Parameters:

font (Font) – the font to use.

SetFontSize(font_size)

Sets the font size of the Widget Annotation.

Parameters:

font_size (double) – the new font size

Notes: A font size of 0 specifies that the text should be autosized to fit in the Widget.

SetHIconLeftOver(hl)

Sets the horizontal leftover space of the icon within the annotation. (Optional)

Parameters:

hl (double) – A number indicating the horizontal leftover space of the icon within the annotation.

Notes: the horizontal leftover space is a number that shall be between 0.0 and 1.0 indicating the fraction of leftover space to allocate at the left. A value of 0.0 shall position the icon at the left of the annotation rectangle. A value of 0.5 shall center it in the horizontal direction within the rectangle. This entry shall be used only if the icon is scaled proportionally. Default value: 0.5.

SetHighlightingMode(args)

Sets the HighlightingMode for the widget annotation. Notes: The annotation’s highlighting mode is the visual effect that shall be used when the mouse button is pressed or held down inside its active area

Parameters:

mode (int) –

• New highlighting mode for the widget.

A highlighting mode other than e_push shall override any down appearance defined for the annotation. Default value: e_invert.

SetIconCaptionRelation(icr)

Sets the Icon and caption relationship of the annotation. (Optional; pushbutton fields only)

Parameters:

icr (int) – A value of the “IconCaptionRelation” enum type. Default value: e_NoIcon.

See also: IconCaptionRelation

SetMouseDownCaptionText(contents)

Sets the button down caption text of the annotation. (Optional; button fields only)

Parameters:

contents (string) – A string containing the button down text of the annotation.

Notes: The button down caption shall be displayed when the mouse button is pressed within its active area.

SetMouseDownIcon(icon)

Sets the Mouse Down icon associated with the annotation. (Optional; button fields only)

Parameters:

icon (Obj) – An SDF object that represents the Mouse Down icon associated with the annotation.

Notes: The Mouse Down icon object is a form XObject defining the annotation’s alternate (down) icon, which shall be displayed when the mouse button is pressed within its active area.

SetRolloverCaptionText(contents)

Sets the roll over caption text of the annotation. (Optional; button fields only)

Parameters:

contents (string) – A string containing the roll over caption text of the annotation.

Notes: The rollover caption shall be displayed when the user rolls the cursor into its active area without pressing the mouse button.

SetRolloverIcon(icon)

Sets the rollover icon associated with the annotation. (Optional; button fields only)

Parameters:

icon (Obj) – An SDF object that represents the rollover icon associated with the annotation.

Notes: The rollover icon object is a form XObject defining the annotation’s rollover icon, which shall be displayed when the user rolls the cursor into its active area without pressing the mouse button.

SetScaleCondition(sd)

Sets the condition under which the icon should be scaled. (Optional)

Parameters:

sd (int) – A value of the “ScaleCondition” enum type. Default value: e_Always.

SetScaleType(st)

Sets the Scale Type of the annotation. (Optional)

Parameters:

st (int) – An entry of the “ScaleType” enum which represents the Scale Type of the annotation. Default value: P.

See also: ScaleType

SetStaticCaptionText(contents)

Sets static caption text of the annotation. (Optional; button fields only)

Parameters:

contents (string) – A string containing the static caption text of the annotation.

Notes: The static caption is the annotation’s normal caption, which shall be displayed when it is not interacting with the user. Unlike the remaining entries with the captions, which apply only to widget annotations associated with pushbutton fields, the Static Caption(CA) entry may be used with any type of button field, including check boxes. This property is part of the Widget appearance characteristics dictionary, this dictionary that shall be used inructing a dynamic appearance stream specifying the annotation’s visual presentation on the page.

SetStaticIcon(icon)

Sets the static icon associated with the annotation. (Optional; button fields only)

Parameters:

icon (Obj) – An SDF object that represents the static icon associated with the annotation.

Notes: The static icon object is a form XObject defining the annotation’s normal icon, which shall be displayed when it is not interacting with the user.

SetTextColor(color, col_comp)

Sets the text color of the Widget Annotation.

Parameters:

• color (ColorPt) – ColorPt object representing the color.

• col_comp (int) – An integer indicating a color space value from the ColorSpace::Type enum. That is, 1 corresponding to “e_device_gray”, 3 corresponding to “e_device_rgb”, and 4 corresponding to “e_device_cmyk”.

SetVIconLeftOver(vl)

Sets the vertical leftover space of the icon within the annotation. (Optional)

Parameters:

vl (double) – A number indicating the vertical leftover space of the icon within the annotation.

Notes: the vertical leftover space is a number that shall be between 0.0 and 1.0 indicating the fraction of leftover space to allocate at the bottom of the icon. A value of 0.0 shall position the icon at the bottom of the annotation rectangle. A value of 0.5 shall center it in the vertical direction within the rectangle. This entry shall be used only if the icon is scaled proportionally. Default value: 0.5.

e_Always = 0

Always scale

e_Anamorphic = 0

e_CAboveI = 3

e_CBelowI = 2

e_CLeftIRight = 5

e_COverlayI = 6

e_CRightILeft = 4

e_Never = 3

Never scale

e_NoCaption = 1

e_NoIcon = 0

e_Proportional = 1

e_WhenBigger = 1

Scale only when the icon is bigger than the annotation rectangle

e_WhenSmaller = 2

Scale only when the icon is smaller than the annotation rectangle

e_invert = 1

Invert the contents of the annotation rectangle.

e_none = 0

No highlighting.

e_outline = 2

Invert the annotation’s border.

e_push = 3

Display the annotation’s down appearance, if any. If no down appearance is defined, the contents of the annotation rectangle shall be offset to appear as if it were being pushed below the surface of the page.

e_toggle = 4

Same as e_push (which is preferred).

property thisown

The membership flag

apryse_sdk.Widget_Create(doc, pos, field)

Creates a new widget annotation in the specified document.

Parameters:

• doc (SDFDoc) – A document to which the annotation is added.

• pos (Rect) – A rectangle specifying the annotation’s bounds in default user space units.

• field (Field) – A form field associated with this widget.

Return type:

Widget

Returns:

A newly created blank widget annotation.

class apryse_sdk.Word(args)

Bases: object

TextExtractor::Word object represents a word on a PDF page. Each word contains a sequence of characters in one or more styles (see TextExtractor::Style).

GetBBox()

Parameters:

out_bbox – The bounding box for this word (in unrotated page coordinates).

Notes: To account for the effect of page ‘/Rotate’ attribute, transform all points using page.GetDefaultMatrix().

GetCharStyle(char_idx)

Parameters:

char_idx (int) – The index of a character in this word.

Return type:

Style

Returns:

The style associated with a given character.

GetCurrentNum()

Return type:

int

Returns:

the index of this word of the current line. A word that starts the line will return 0, whereas the last word in the line will return (line.GetNumWords()-1).

GetGlyphQuad(glyph_idx)

Parameters:

• glyph_idx (int) – The index of a glyph in this word.

• out_quad – The quadrilateral representing a tight bounding box for a given glyph in the word (in unrotated page coordinates).

GetNextWord()

Return type:

Word

Returns:

the next word on the current line.

GetNumGlyphs()

Return type:

int

Returns:

The number of glyphs in this word.

GetQuad()

Parameters:

out_quad – The quadrilateral representing a tight bounding box for this word (in unrotated page coordinates).

GetString()

Return type:

string

Returns:

the content of this word represented as a Unicode string.

GetStringLen()

Return type:

int

Returns:

the number of characters in this word.

GetStyle()

Return type:

Style

Returns:

predominant style for this word.

IsValid()

Return type:

boolean

Returns:

true if this is a valid word, false otherwise.

property mp_word

property thisown

The membership flag

class apryse_sdk.WordOutputOptions

Bases: object

A class containing options common to ToWord functions

SetConnectHyphens(connect)

Specifies whether hyphens in the PDF should be connected. Default is false.

Parameters:

connect (boolean) – if true, hyphens in the PDF will be connected.

SetCustomOCRLanguage(ocrlang)

Specifies the custom OCR languages to use. Notes: Use 3-letter ISO 639-2 language codes, separated by spaces. Example: “eng deu spa fra”. The default is English.

Parameters:

ocrlang (string) – the OCR language(s).

SetLanguage(language)

Specifies the OCR language. Default is automatic language detection.

Parameters:

language (int) – the OCR language.

SetPDFPassword(password)

Specifies the password if the PDF requires one.

Parameters:

password (string) – the PDF password, if required; an empty string otherwise.

SetPages(page_from, page_to)

Specifies a range of pages to be converted. By default all pages are converted. The first page has the page number of 1.

Parameters:

• page_from (int) – the first page to be converted.

• page_to (int) – the last page to be converted (inclusive). Use a negative value to specify the last page in the PDF.

SetPreferredOCREngine(engine)

Specifies preferred OCR engine.

Parameters:

engine (int) – The PreferredOCREngine to OCR.

SetPrioritizeVisualAppearance(replica)

Specifies whether to prefer an exact visual replica of the PDF at the expense of preventing reflow of document paragraphs. Default is false.

Parameters:

replica (boolean) – False is preferred for most documents that contain paragraphs. Consider using true for documents that don’t flow, such as CAD drawings, Illustrator-generated files.

SetSearchableImageSetting(setting)

Specifies how scanned image pages should be converted. Default is e_ocr_text.

Parameters:

setting (int) – the searchable image setting.

Remarks: Pre-existing OCRed content is ignored and a new OCR is performed from scratch. See also: SearchableImageSetting

SetWordOutputFormat(format)

Specifies the output document format (DOCX, RTF, TXT). It is the most useful when the output file extension is not .docx, .rtf or .txt.

Parameters:

format (int) – the output document format (DOCX, RTF, TXT).

Remarks: The DOC file format is now deprecated, DOCX is used automatically instead. See also: WordOutputFormat

e_ocr_always = 4

e_ocr_image = 1

e_ocr_image_text = 0

e_ocr_off = 3

e_ocr_text = 2

e_wof_doc = 1

e_wof_docx = 0

e_wof_rtf = 2

e_wof_txt = 3

property thisown

The membership flag

class apryse_sdk.WordToPDFOptions

Bases: ConversionOptions

GetLayoutResourcesPluginPath()

Gets the value LayoutResourcesPluginPath from the options object The path at which the pdftron-provided font resource plugin resides

Return type:

string

Returns:

a string, The path at which the pdftron-provided font resource plugin resides.

GetResourceDocPath()

Gets the value ResourceDocPath from the options object The path at which the a .docx resource document resides

Return type:

string

Returns:

a string, The path at which the a .docx resource document resides.

GetSmartSubstitutionPluginPath()

Gets the value SmartSubstitutionPluginPath from the options object The path at which the pdftron-provided font resource plugin resides

Return type:

string

Returns:

a string, The path at which the pdftron-provided font resource plugin resides.

SetLayoutResourcesPluginPath(value)

Sets the value for LayoutResourcesPluginPath in the options object The path at which the pdftron-provided font resource plugin resides

Parameters:

value: – The path at which the pdftron-provided font resource plugin resides

Return type:

WordToPDFOptions

Returns:

this object, for call chaining

SetResourceDocPath(value)

Sets the value for ResourceDocPath in the options object The path at which the a .docx resource document resides

Parameters:

value: – The path at which the a .docx resource document resides

Return type:

WordToPDFOptions

Returns:

this object, for call chaining

SetSmartSubstitutionPluginPath(value)

Sets the value for SmartSubstitutionPluginPath in the options object The path at which the pdftron-provided font resource plugin resides

Parameters:

value: – The path at which the pdftron-provided font resource plugin resides

Return type:

WordToPDFOptions

Returns:

this object, for call chaining

property thisown

The membership flag

class apryse_sdk.X501AttributeTypeAndValue(args)

Bases: object

This class represents an AttributeTypeAndValue as mentioned in RFC 5280 in the context of DistinguishedNames and as defined in ITU X.501.

Destroy()

GetAttributeTypeOID()

Retrieves the OID (i.e. one of the object identifiers from the X.500 attribute types) in the form of integer components in a container.

Return type:

ObjectIdentifier

Returns:

an ObjectIdentifier object.

GetStringValue()

Retrieves the value associated with the contained OID (object identifier) as a string, if the value is defined by the OID to be of a string type.

Return type:

string

Returns:

a string containing the string value.

property m_impl

property thisown

The membership flag

class apryse_sdk.X501DistinguishedName(args)

Bases: object

This class represents a distinguished name (DN) as defined in X.501. See the X.500 standards, RFC 5280, and an OID repository for more information.

Destroy()

GetAllAttributesAndValues()

Retrieves all of the attribute-type-to-value pairs in this distinguished name.

Return type:

std::vector< Crypto::X501AttributeTypeAndValue,std::allocator< Crypto::X501AttributeTypeAndValue > >

Returns:

a container of X501AttributeTypeAndValue objects

GetStringValuesForAttribute(in_oid)

Returns a container full of string representations of all the values in this distinguished name that match a particular attribute’s object identifier (OID). If an attribute’s OID defines the corresponding value to not be of a string type, then that value will not be returned from this function.

Parameters:

in_oid (ObjectIdentifier) – the object identifier representing the sought attribute.

Return type:

std::vector< std::string,std::allocator< std::string > >

Returns:

a container of string values containing any strings associated with the supplied attribute

HasAttribute(in_oid)

Returns whether this distinguished name contains a particular attribute, identified by its object identifier (OID).

Parameters:

in_oid (ObjectIdentifier) – the object identifier representing the sought attribute.

Return type:

boolean

Returns:

a boolean value representing whether this distinguished name contains the supplied attribute.

property m_impl

property thisown

The membership flag

class apryse_sdk.X509Certificate(args)

Bases: object

This class represents an X509 public-key certificate, as specified in RFC 5280.

Destroy()

GetData()

Retrieves the certificate as binary DER-encoded data. (DER is short for Distinguished Encoding Rules.).

Return type:

std::vector< UChar,std::allocator< UChar > >

Returns:

a container of bytes representing the certificate, encoded as binary DER.

GetExtensions()

Retrieves all extensions (as first specified in V3 of X509, see RFC 5280) from the certificate.

Return type:

std::vector< Crypto::X509Extension,std::allocator< Crypto::X509Extension > >

Returns:

a container of X509Extension objects.

GetFingerprint(args)

Retrieves, in a string, a text representation of a cryptographically-secure digest of the certificate that can be used to identify it uniquely.

Parameters:

in_digest_algorithm (int) – An enumeration representing the digest algorithm to use. Currently supported are SHA-1 (SHA-160), SHA-256, SHA-384, and SHA-512.

Return type:

string

Returns:

a string representation of the fingerprint, in the form of double ASCII characters representing hex bytes, separated by colons

Notes: Default algorithm parameter is currently SHA-256, but may change in future without further warning, pursuant to security needs.

GetIssuerField()

Retrieves the names of the certificate issuer as a map of OIDs (i.e. one of the object identifiers from the X.500 attribute types) to string values. The issuer field identifies the entity that has signed and issued the certificate. The returned value will contain all of the AttributeTypeAndValue items from all of the RelativeDistinguishedNames in the Name of the issuer. See RFC 5280, section 4.1.2.4 and Appendix A.1 (page 116).

Return type:

X501DistinguishedName

Returns:

an X501DistinguishedName object

GetNotAfterEpochTime()

Retrieves the notAfter time from the certificate’s Validity entry in the form of an integral value representing an epoch time.

Return type:

int

Returns:

an integer containing an epoch time

GetNotBeforeEpochTime()

Retrieves the notBefore time from the certificate’s Validity entry in the form of an integral value representing an epoch time.

Return type:

int

Returns:

an integer containing an epoch time

GetRawX509VersionNumber()

Retrieves the version number representing which version of X509 the certificate corresponds to, from the certificate.

Return type:

int

Returns:

an integer containing the version number

Notes: The X509 version number in the certificate, which we return unchanged here, is zero-indexed and therefore is one less in value than the actual version. e.g. X509v3 is represented by a returned version number of 2.

GetSerialNumber()

Retrieves the serialNumber entry from the certificate.

Return type:

std::vector< UChar,std::allocator< UChar > >

Returns:

a big-integer-style container holding bytes representing the components of an integral serial number in big-endian order.

GetSubjectField()

Retrieves the names of the certificate subject as a map of OIDs (i.e. one of the

object identifiers from the X.500 attribute types) to string values. The subject field represents the identity of the entity associated with the certificate’s public key. The returned value will contain all of the AttributeTypeAndValue items from all of the RelativeDistinguishedNames in the Name of the subject. See RFC 5280, section 4.1.2.6 and Appendix A.1 (page 116).

Return type:

X501DistinguishedName

Returns:

an X501DistinguishedName object

ToString()

Returns a string representation of the certificate.

Return type:

string

Returns:

a string representation of the certificate.

Notes: Output may change in future versions.

property m_impl

property thisown

The membership flag

class apryse_sdk.X509Extension(args)

Bases: object

This class represents an X509v3 certificate extension. See RFC 5280 as a specification.

Destroy()

GetData()

Retrieves the raw binary DER-encoded data of the extension. (DER is short for Distinguished Encoding Rules.)

Return type:

std::vector< UChar,std::allocator< UChar > >

Returns:

a container holding the bytes of the extension in the form of binary DER-encoded data

GetObjectIdentifier()

Retrieves the OID (object identifier) of the extension in the form of integer components in a container. The meaning of an OID can be determined from an OID repository.

Return type:

ObjectIdentifier

Returns:

an ObjectIdentifier object.

IsCritical()

Retrieves whether the extension is ‘critical’. See RFC 5280 for an explanation of what this means.

Return type:

boolean

Returns:

a boolean representing the criticality flag of the extension.

ToString()

Returns a string representation of the extension.

Return type:

string

Returns:

a string representation of the extension.

Notes: Output may change in future versions.

property m_impl

property thisown

The membership flag

class apryse_sdk.XODOutputOptions

Bases: XPSOutputCommonOptions

A class containing options for ToXod functions

SetAnnotationOutput(annot_output)

Choose how to output annotations. Default is e_internal_xfdf.

Parameters:

annot_output (int) – the flag to specify the output option

SetElementLimit(element_limit)

If rendering is permitted, sets the maximum number of page elements before that page will be rendered. Default is 2000000000 which will never cause pages to be completely rendered in this manner.

Parameters:

element_limit (int) – the maximum number of elements before a given page will be rendered

SetEncryptPassword(_pass)

Encrypt XOD parts with AES 128 encryption using the supplied password. This option is not available when using SetExternalParts(true)

Parameters:

pass (string) – the encryption password

SetExternalParts(generate)

Output XOD as a collection of loose files rather than a zip archive. This option should be used when using the external part retriever in Webviewer. Default is false.

Parameters:

generate (boolean) – if true XOD is output as a collection of loose files

SetExtractUsingZorder(use_zorder)

Sets whether text extraction uses Z-order as reading order. Default is false.

Parameters:

use_zorder (boolean) – if true text extraction uses Z-order as reading order.

SetFlattenContent(flatten)

Flatten images and paths into a single background image overlaid with vector text. This option can be used to improve speed on devices with little processing power such as iPads. Default is e_high_quality.

Parameters:

flatten (int) – select which flattening mode to use.

SetFlattenThreshold(threshold)

Used to control how precise or relaxed text flattening is. When some text is preserved (not flattened to image) the visual appearance of the document may be altered.

Parameters:

threshold (int) – the threshold setting to use.

SetJPGQuality(quality)

Specifies the compression quality to use when generating JPEG images.

Parameters:

quality (int) – the JPEG compression quality, from 0(highest compression) to 100(best quality).

SetMaximumImagePixels(max_pixels)

Specifies the maximum image slice size in pixels. Default is 2000000. Notes: This setting now will no longer reduce the total number of image pixels. Instead a lower value will just produce more slices and vice versa. Since image compression works better with more pixels a larger max pixels should generally create smaller files.

Parameters:

max_pixels (int) – the maximum number of pixels an image can have

SetOpacityMaskWorkaround(opacity_render)

If rendering is permitted, sets whether pages containing opacity masks should be rendered. This option is used as a workaround to a bug in Silverlight where opacity masks are transformed incorrectly. Default is false.

Parameters:

opacity_render (boolean) – if true pages with opacity masks will be rendered

SetOutputThumbnails(include_thumbs)

Sets whether per page thumbnails should be included in the file. Default is true.

Parameters:

include_thumbs (boolean) – if true thumbnails will be included

SetPreferJPG(prefer_jpg)

Where possible output JPG files rather than PNG. This will apply to both thumbnails and document images. Default is true.

Parameters:

prefer_jpg (boolean) – if true JPG images will be used whenever possible.

SetSilverlightTextWorkaround(workaround)

Outputs rotated text as paths. This option is used as a workaround to a bug in Silverlight where pages with rotated text could cause the plugin to crash. Default is false.

Parameters:

workaround (boolean) – if true rotated text will be changed to paths

SetThumbnailSize(args)

Overload 1:

The width and height of a square in which thumbnails will be contained. Default is 400 for normal pages and 1500 for large pages. Notes: A large page is a page larger than twice the area of the standard page size (8.5 X 11).

Parameters:

size (int) – the maximum dimension (width or height) that thumbnails will have.

Overload 2:

The width and height of squares in which thumbnails will be contained. Default is 400 for normal pages and 1500 for large pages. Notes: A large page is a page larger than twice the area of the standard page size (8.5 X 11).

Parameters:

• regular_size (int) – the maximum dimension that thumbnails for regular size pages will have.

• large_size (int) – the maximum dimension that thumbnails for large pages will have.

UseSilverlightFlashCompatible(compatible)

The latest XOD format is only partially supported in Silverlight and Flash due to various optimizations in the text format and the addition of blend mode support. This option forces the converter to use an older version of XOD that is Silverlight/Flash compatible but does not have these improvements. By default the latest XOD format is generated.

Parameters:

compatible (boolean) – if true will use the older XOD format which is not compatible with Silverlight/Flash

e_external_xfdf = 1

e_flatten = 2

e_internal_xfdf = 0

property thisown

The membership flag

class apryse_sdk.XPSOutputCommonOptions

Bases: object

A class containing options common to ToXps and ToXod functions

GenerateURLLinks(generate)

Sets whether links should be generated from urls found in the document. Default is false.

Parameters:

generate (boolean) – if true links will be generated from urls

SetDPI(dpi)

The output resolution, from 1 to 1000, in Dots Per Inch (DPI) at which to render elements which cannot be directly converted. Default is 140.

Parameters:

dpi (int) – the resolution in Dots Per Inch

SetOverprint(mode)

Enable or disable support for overprint and overprint simulation. Overprint is a device dependent feature and the results will vary depending on the output color space and supported colorants (i.e. CMYK, CMYK+spot, RGB, etc). Default is e_op_pdfx_on.

Parameters:

mode (int) – e_op_on: always enabled; e_op_off: always disabled; e_op_pdfx_on: enabled for PDF/X files only.

SetPrintMode(print_mode)

Sets whether ToXps should be run in print mode. Default is false.

Parameters:

print_mode (boolean) – if true print mode is enabled

SetRenderPages(render)

Sets whether rendering of pages should be permitted when necessary to guarantee output. Default is true.

Parameters:

render (boolean) – if false rendering is not permitted under any circumstance

SetThickenLines(thicken)

Sets whether thin lines should be thickened. Default is true for XPS and false for XOD.

Parameters:

thicken (boolean) – if true then thin lines will be thickened

e_op_off = 0

e_op_on = 1

e_op_pdfx_on = 2

property m_obj

property thisown

The membership flag

class apryse_sdk.XPSOutputOptions

Bases: XPSOutputCommonOptions

A class containing options for ToXps functions

SetOpenXps(openxps)

Sets whether the output format should be open xps. Default is Microsoft xps output.

Parameters:

openxps (boolean) – if true open xps output is used

property thisown

The membership flag

apryse_sdk.e_downloadedtype_failed = 5

An error has occurred while downloading and downloading has stopped.

apryse_sdk.e_downloadedtype_finished = 4

The entire document has been downloaded.

apryse_sdk.e_downloadedtype_named_dests = 2

The named destinations have been downloaded. These may be necessary for link activation.

apryse_sdk.e_downloadedtype_opened = 6

The initial document information is available and it is now ok to query for document information.

apryse_sdk.e_downloadedtype_outline = 3

The document outline (bookmarks) has been downloaded.

apryse_sdk.e_downloadedtype_page = 0

A new page has been downloaded.

apryse_sdk.e_downloadedtype_thumb = 1

A thumbnail has been downloaded.