OLE Automation

This chapter describes the objects, data types, and methods in the OLE automation interface.

The names AcroExch.App and AxAcroPDFLib.AxAcroPDF are the external strings OLE clients use to create objects of certain types. The Acrobat developer type libraries call them CAcro.App and AcroPDFLib, respectively.

Acrobat supports dual interfaces, so the methods all have a return type of HResult.

The following table summarizes the available objects and data types.

Object

Description

testlink AcroExch.App

The application itself.

AcroExch.AVDoc

A document as seen in the user interface.

AcroExch.PDDoc

The underlying PDF representation of a document.

AcroExch.HiliteList

An entry in a highlight list.

AcroExch.AVPageView

The area of the window that displays the contents of a page.

AcroExch.PDPage

A single page in the PDF representation of a document.

AcroExch.PDAnnot

An annotation on a page in the PDF file.

AcroExch.PDBookmark

A bookmark in a PDF file.

AcroExch.PDTextSelect

A selection of text on a single page.

AxAcroPDFLib.AxAcroPDF

An object containing PDF browser controls.

AcroExch.Point

A point, specified by its x–coordinate and y–coordinate.

AcroExch.Rect

A rectangle, specified by the top-left and bottom-right points.

AcroExch.Time

A specified time, accurate to the millisecond.

AcroExch.App

The Acrobat application itself. This is a creatable interface. From the application layer, you can control the appearance of Acrobat, whether Acrobat appears, and the size of the application window. This object provides access to the menu bar and the toolbar, as well as the visual representation of a PDF file on the screen (through an AVDoc object).

Methods

The App object has the following methods.

Method

Description

CloseAllDocs

Closes all open documents.

Exit

Exits Acrobat.

GetActiveDoc

Gets the frontmost document.

GetActiveTool

Gets the name of the currently active tool.

GetAVDoc

Gets an AcroExch.AVDoc object via its index within the list of open AVDoc objects.

GetFrame

Gets the window’s frame.

GetInterface

Gets an IDispatch interface for a named object, typically a third-party plug-in.

GetLanguage

Gets a code that specifies which language the Acrobat application’s user interface is using.

GetNumAVDocs

Gets the number of open AcroExch.AVDoc objects.

GetPreference

Gets a value from the preferences file.

GetPreferenceEx

Gets the specified application preference, using the VARIANT type to pass values.

Hide

Hides the Acrobat application.

Lock

Locks the Acrobat application.

Minimize

Minimizes the Acrobat application.

Maximize

Maximizes the Acrobat application.

MenuItemExecute

Executes the menu item whose language-independent menu item name is specified.

MenuItemIsEnabled

Determines whether the specified menu item is enabled.

MenuItemIsMarked

Determines whether the specified menu item is marked.

MenuItemRemove

Removes the menu item whose language-independent menu item is specified.

Restore

Restores the main window of the Acrobat application.

SetActiveTool

Sets the active tool according to the specified name, and determines whether the tool is to be used only once or should remain active after being used (persistent).

SetFrame

Sets the window’s frame to the specified rectangle.

SetPreference

Sets a value in the preferences file.

SetPreferenceEx

Sets the application preference specified by nType to the value stored at pVal.

Show

Shows the Acrobat application.

ToolButtonIsEnabled

Determines whether the specified toolbar button is enabled.

ToolButtonRemove

Removes the specified button from the toolbar.

Unlock

Unlocks the Acrobat application if it was previously locked.

UnlockEx

Unlocks the Acrobat application if it was previously locked.

CloseAllDocs

Closes all open documents. You can close each individual AVDoc object by calling AVDoc. Close.

You must explicitly close all documents or call App.CloseAllDocs. Otherwise, the process never exits.

Syntax

VARIANT_BOOL CloseAllDocs();

Returns

-1 if successful, 0 if not.

Related methods

Exit

Exits Acrobat. Applications should call App.Exit before exiting.

Note

Use App. CloseAllDocs to close all the documents before calling this method.

Syntax

VARIANT_BOOL Exit();

Returns

Returns -1 if the entire shutdown process succeeded. This includes closing any open documents, releasing OLE references, and finally exiting the application. If any step fails, the function returns 0, and the application continues running. This method does not work if the application is visible (if the user is in control of the application). In such cases, if the Show method had previously been called, you can call Hide and then Exit.

GetActiveDoc

Gets the frontmost document.

Syntax

LPDISPATCH GetActiveDoc();

Returns

The LPDISPATCH for the frontmost AcroExch.AVDoc object. If there are no documents open, it returns NULL.

GetActiveTool

Gets the name of the currently active tool.

Syntax

BSTR GetActiveTool();

Returns

Returns NULL if there is no active tool . Returns the name of the currently active tool otherwise. See the PDF Library documentation for a list of tool names.

GetAVDoc

Gets an AcroExch.AVDoc object from its index within the list of open AVDoc objects. Use App. GetNumAVDocs to determine the number of AcroExch.AVDoc objects.

Syntax

LPDISPATCH GetAVDoc(long nIndex);

Parameters

Parameter

Description

nIndex

The index of the document to get.

Returns

The LPDISPATCH for the specified AcroExch.AVDoc document, or NULL if nIndex is greater than the number of open documents.

GetFrame

Gets the window’s frame.

GetFrame is not useful when the PDF file was opened with AVDoc. OpenInWindow. GetFrame returns the application window’s frame (not the document window’s frame). However, the application’s window is hidden when a document is opened using OpenInWindow , and does not change in size as document windows are moved and resized.

This method is also not useful if the Acrobat application is in single document interface (SDI) mode.

Syntax

LPDISPATCH GetFrame();

Returns

The LPDISPATCH for the window’s frame, specified as an AcroExch.Rect.

If the Acrobat application is in SDI mode, a [0,0,0,0] Rect is returned.

GetInterface

Gets an IDispatch interface for a named object, typically a third-party plug-in. This is an entry point to functionality that is undefined and which must be provided by the plug-in author. If you are accessing third-party functionality through GetInterface, ask the author for additional information.

Syntax

LPDISPATCH GetInterface (BSTR szName);

Parameters

Parameter

Description

szName

Name of the object.

Returns

The LPDISPATCH for the objects’s interface or NULL if the object was not found.

GetLanguage

Gets a code that specifies which language the Acrobat application’s user interface is using.

Syntax

BSTR GetLanguage();

Returns

String containing a three-letter language code. Must be one of the following:

  • DEU-German

  • ENU-English

  • ESP-Spanish

  • FRA-French

  • ITA-Italian

  • NLD-Dutch

  • SVE-Swedish

GetNumAVDocs

Gets the number of open AcroExch.AVDoc objects. The maximum number of documents the Acrobat application can open at a time is specified by the avpMaxOpenDocuments preference, which can be obtained with App. GetPreferenceEx and set by App. SetPreferenceEx.

Syntax

long GetNumAVDocs();

Returns

The number of open AcroExch.AVDoc objects.

">

GetPreference

Note

This method is deprecated; use GetPreferenceEx instead. GetPreference is unable to accept important data types such as strings, but GetPreferenceEx can convert many data types into acceptable formats.

Gets a value from the preferences file. Zoom values (used in avpDefaultZoomScale and avpMaxPageCacheZoom) are returned as percentages (for example, 1.00 is returned as 100). Colors (used in avpNoteColorPDcolorValue) are automatically converted to RGB values from the representation used in the preferences file.

Syntax

long GetPreference(short nType);

Parameters

Parameter

Description

nType

The preferences item whose value is set. For more information, see the PDF Library documentation.

Returns

The value of the specified preference item.

GetPreferenceEx

Gets the specified application preference, using the VARIANT type to pass values.

Syntax

VARIANT GetPreferenceEx(short nType);

Parameters

Parameter

Description

nType

The name of the preferences item whose value is obtained.

Returns

The value of the specified preference item.

Hide

Hides the Acrobat application. When the viewer is hidden, the user has no control over it, and the Acrobat application exits when the last automation object is closed.

Syntax

VARIANT_BOOL Hide();

Returns

-1 if successful, 0 if not.

Lock

Locks the Acrobat application. Typically, this method is called when using AVDoc. OpenInWindowEx to draw into another application’s window. If you call App.Lock, you should call App. UnlockEx when you are done using OLE automation.

There are some advantages and disadvantages of locking the viewer when using AVDoc. OpenInWindowEx. You must consider these before deciding whether to lock the viewer:

  • Locking prevents problems that can sometimes occur if two processes are trying to open a file at the same time.

  • Locking prevents a user from using Acrobat’s user interface (such as adding annotations) in your application’s window.

  • Locking can prevent any other application, including the Acrobat application, from opening PDF files. This problem can be minimized by calling App. UnlockEx as soon as the file has been opened.

Syntax

VARIANT_BOOL Lock(BSTR szLockedBy);

Parameters

Parameter

Description

szLockedBy

A string that is used as the name of the application that has locked the Acrobat application.

Returns

-1 if the Acrobat application was locked successfully, 0 otherwise. Locking fails if the Acrobat application is visible.

Minimize

Minimizes the Acrobat application.

Syntax

VARIANT_BOOL Minimize(long BMinimize);

Parameters

Parameter

Description

BMinimize

If a positive number, the Acrobat application is minimized. If 0, the Acrobat application is returned to its normal state.

Returns

-1 if successful, 0 if not.

Maximize

Maximizes the Acrobat application.

Syntax

VARIANT_BOOL Maximize(long bMaximize);

Parameters

Parameter

Description

bMaximize

If a positive number, the Acrobat application is maximized. If 0, the Acrobat application is returned to its normal state.

Returns

-1 if successful, 0 if not.

Restore

Restores the main window of the Acrobat application. Calling this with bRestore set to a positive number causes the main window to be restored to its original size and position and to become active.

Syntax

VARIANT_BOOL Restore(long bRestore);

Parameters

Parameter

Description

bRestore

If a positive number, the Acrobat application is restored, 0 otherwise.

Returns

-1 if successful, 0 if not.

SetActiveTool

Sets the active tool according to the specified name, and determines whether the tool is to be used only once or should remain active after being used (persistent).

Syntax

VARIANT_BOOL SetActiveTool(BSTR szButtonName,
                          long bPersistent);

Parameters

Parameter

Description

szButtonName

The name of the tool to set as the active tool. See the PDF Library documentation for a list of tool names.

bPersistent

A request indicating whether the tool should be persistent. A positive number indicates a request to the Acrobat application for the tool to remain active after it has been used. If 0 is specified, the Acrobat application reverts to the previously active tool after this tool is used once.

Returns

-1 if the tool was set, 0 otherwise.

SetFrame

Sets the window’s frame to the specified rectangle. This method has no effect if the Acrobat application is in single document interface (SDI) mode.

Syntax

VARIANT_BOOL SetFrame(LPDISPATCH iAcroRect);

Parameters

Parameter

Description

iAcroRect

The LPDISPATCH for an AcroExch.Rect specifying the window frame. iAcroRect contains the instance variable m_lpDispatch, which contains the LPDISPATCH.

Returns

-1 if the frame was set, 0 if iAcroRect is not of type AcroExch.Rect.

SetPreference

Note

This method is deprecated; use SetPreferenceEx instead. SetPreference is unable to accept important data types such as strings, but SetPreferenceEx can convert many data types into acceptable formats.

Sets a value in the preferences file. Zoom values (used in avpDefaultZoomScale and avpMaxPageCacheZoom) must be passed as percentages and are automatically converted to fixed point numbers (for example, 100 is automatically converted to 1.0). Colors (used in avpHighlightColor or avpNoteColor) are automatically converted from RGB values to the representation used in the preferences file.

Syntax

VARIANT_BOOL SetPreference(short nType, long nValue);

Parameters

Parameter

Description

nType

The preferences item whose value is set. See the PDF Library documentation for a list of preference items.

nValue

The value to set.

Returns

-1 if successful, 0 if not.

SetPreferenceEx

Sets the application preference specified by nType to the value stored at pVal. If pVal has a non-conforming VARTYPE, SetPreferenceEx performs type conversion. For example, a string representation of an integer is converted to an actual integer.

Syntax

VARIANT_BOOL SetPreferenceEx(short nType, VARIANT* pVal);

Parameters

Parameter

Description

nType

The preferences item whose value is set. See the PDF Library documentation for a list of preference items.

pVal

The value to set.

Returns

Returns -1 if nType is a supported type or the type conversion is successful, 0 otherwise.

Show

Shows the Acrobat application. When the viewer is shown, the user is in control, and the Acrobat application does not automatically exit when the last automation object is destroyed. However, it will exit if no documents are being displayed.

Syntax

VARIANT_BOOL Show();

Returns

-1 if successful, 0 if not.

ToolButtonIsEnabled

Determines whether the specified toolbar button is enabled.

Syntax

VARIANT_BOOL ToolButtonIsEnabled(BSTR szButtonName);

Parameters

Parameter

Description

szButtonName

The name of the button whose enabled state is checked. See the PDF Library documentation for a list of toolbar button names.

Returns

-1 if the button is enabled, 0 if it is not enabled or does not exist.

ToolButtonRemove

Removes the specified button from the toolbar.

Syntax

VARIANT_BOOL ToolButtonRemove(BSTR szButtonName);

Parameters

Parameter

Description

szButtonName

The name of the button to remove. See the PDF Library documentation for a list of toolbar button names.

Returns

-1 if the button was removed, 0 otherwise.

Unlock

Note

In version 4.0 or later, use App. UnlockEx instead.

Unlocks the Acrobat application if it was previously locked. This method clears a flag that indicates the viewer is locked. If you called App. Lock , you should call App.Unlock when you are done using OLE automation.

Use App. Lock and App . UnlockEx if you call OpenInWindow.

Typically, you call App. Lock when your application initializes and App.Unlock in your application’s destructor method.

Syntax

VARIANT_BOOL Unlock();

Returns

-1 if successful, 0 if not.

UnlockEx

Unlocks the Acrobat application if it was previously locked.

Syntax

VARIANT_BOOL UnlockEx (BSTR szLockedBy);

Parameters

Parameter

Description

szLockedBy

A string indicating the name of the application to be unlocked.

Returns

-1 if successful, 0 if not.

AcroExch.AVDoc

A view of a PDF document in a window. This is a creatable interface. There is one AVDoc object per displayed document. Unlike a PDDoc object, an AVDoc object has a window associated with it.

Methods

The AVDoc object has the following methods.

Method

Description

BringToFront

Brings the window to the front.

ClearSelection

Clears the current selection.

Close

Closes a document.

FindText

Finds the specified text, scrolls so that it is visible, and highlights it.

GetAVPageView

Gets the AcroExch.AVPageView associated with an AcroExch.AVDoc.

GetFrame

Gets the rectangle specifying the window’s size and location.

GetPDDoc

Gets the AcroExch.PDDoc associated with an AcroExch.AVDoc.

GetTitle

Gets the window’s title.

GetViewMode

Gets the current document view mode (pages only, pages and thumbnails, or pages and bookmarks).

IsValid

Determines whether the AcroExch.AVDoc is still valid.

Maximize

Maximizes the window if bMaxSize is a positive number.

Open

Opens a file.

OpenInWindow

Opens a PDF file and displays it in a user-specified window.

OpenInWindowEx

Opens a PDF file and displays it in a user-specified window.

PrintPages

Prints a specified range of pages displaying a print dialog box.

PrintPagesEx

Prints a specified range of pages, displaying a print dialog box.

PrintPagesSilent

Prints a specified range of pages without displaying any dialog box.

PrintPagesSilentEx

Prints a specified range of pages without displaying any dialog box.

SetFrame

Sets the window’s size and location.

SetTextSelection

Sets the document’s selection to the specified text selection.

SetTitle

Sets the window’s title.

SetViewMode

Sets the mode in which the document will be viewed (pages only, pages and thumbnails, or pages and bookmarks)

ShowTextSelect

Changes the view so that the current text selection is visible.

BringToFront

Brings the window to the front.

Syntax

VARIANT_BOOL BringToFront();

Returns

Returns 0 if no document is open, -1 otherwise.

ClearSelection

Clears the current selection.

Syntax

VARIANT_BOOL ClearSelection();

Returns

Returns -1 if the selection was cleared, 0 if no document is open or the selection could not be cleared.

Close

Closes a document. You can close all open AVDoc objects by calling App. CloseAllDocs.

To reuse an AVDoc object, close it with AVDoc. Close , then use the AVDoc object’s LPDISPATCH for AVDoc. OpenInWindow.

Syntax

VARIANT_BOOL Close(long bNoSave);

Parameters

Parameter

Description

bNoSave

If a positive number, the document is closed without saving it. If 0 and the document has been modified, the user is asked whether or not the file should be saved.

Returns

Always returns -1, even if no document is open.

FindText

Finds the specified text, scrolls so that it is visible, and highlights it.

Syntax

VARIANT_BOOL FindText(BSTR szText, long bCaseSensitive, long bWholeWordsOnly, long bReset);

Parameters

Parameter

Description

szText

The text to be found.

bCaseSensitive

If a positive number, the search is case-sensitive. If 0, it is case-insensitive.

bWholeWordsOnly

If a positive number, the search matches only whole words. If 0, it matches partial words.

bReset

If a positive number, the search begins on the first page of the document. If 0, it begins on the current page.

Returns

-1 if the text was found, 0 otherwise.

GetAVPageView

Gets the AcroExch.AVPageView associated with an AcroExch.AVDoc.

Syntax

LPDISPATCH GetAVPageView();

Returns

The LPDISPATCH for the AcroExch.AVPageView or NULL if no document is open.

GetFrame

Gets the rectangle specifying the window’s size and location.

Syntax

LPDISPATCH GetFrame();

Returns

The LPDISPATCH for an AcroExch.Rect containing the frame, or NULL if no document is open.

GetPDDoc

Gets the AcroExch.PDDoc associated with an AcroExch.AVDoc.

Syntax

LPDISPATCH GetPDDoc();

Returns

The LPDISPATCH for the AcroExch.PDDoc or NULL if no document is open.

GetTitle

Gets the window’s title.

Syntax

BSTR GetTitle();

Returns

The window’s title or NULL if no document is open.

GetViewMode

Gets the current document view mode (pages only, pages and thumbnails, or pages and bookmarks).

Syntax

long GetViewMode();

Returns

The current document view mode or 0 if no document is open. The return value is one of the following:

  • PDDontCare: 0: leave the view mode as it is

  • PDUseNone: 1: display without bookmarks or thumbnails

  • PDUseThumbs: 2: display using thumbnails

  • PDUseBookmarks: 3: display using bookmarks

  • PDFullScreen: 4: display in full screen mode

IsValid

Determines whether the AcroExch.AVDoc is still valid. This method only checks if the document has been closed or deleted; it does not check the internal structure of the document.

Syntax

VARIANT_BOOL IsValid();

Returns

-1 if the document can still be used, 0 otherwise.

Maximize

Maximizes the window if bMaxSize is a positive number.

Syntax

VARIANT_BOOL Maximize(long bMaxSize);

Parameters

Parameter

Description

bMaxSize

Indicates whether the window should be maximized.

Returns

-1 if a document is open, 0 otherwise.

Open

Opens a file. A new instance of AcroExch.AVDoc must be created for each displayed PDF file.

Note

An application must explicitly close any AVDoc that it opens by calling AVDoc. Close (the destructor for the AcroExch.AVDoc class does not call AVDoc. Close).

Syntax

VARIANT_BOOL Open(BSTR szFullPath, BSTR szTempTitle);

Parameters

Parameter

Description

szFullPath

The full path of the file to open.

szTempTitle

An optional title for the window in which the file is opened. If szTempTitle is NULL or the empty string, it is ignored. Otherwise, szTempTitle is used as the window title.

Returns

-1 if the file was opened successfully, 0 otherwise.

OpenInWindow

Note

As of Acrobat 3.0, this method simply returns false. Use the method AVDoc. OpenInWindowEx instead.

Syntax

VARIANT_BOOL OpenInWindow(BSTR fileName, short hWnd);

Parameters

Parameter

Description

fileName

The full path of the file to open.

hWnd

Handle for the window in which the file is displayed.

Returns

-1

OpenInWindowEx

Opens a PDF file and displays it in a user-specified window. The default Windows file system is used to open the file.

Note

Acrobat uses only its built-in implementation of the file opening code—not any replacement file system version that a developer might have added with a plug-in.

An application must explicitly close any AVDoc that it opens by calling AVDoc. Close (the destructor for the AcroExch.AVDoc class does not call AVDoc. Close ).

Do not set the view mode to Close with AVDoc. SetViewMode when using AVDoc. OpenInWindowEx ; this will cause the viewer and application to hang.

If you use a view mode of AV_PAGE_VIEW, the pagemode parameter will be ignored.

See AVApp. Lock for a discussion of whether to lock the viewer before making this call.

Syntax

VARIANT_BOOL OpenInWindowEx(LPCTSTR szFullPath, long hWnd,

                 long openFlags, long useOpenParams

                 long pgNum, short pageMode,

                 short zoomType, long zoom, short top,

                 short left);

Parameters

Parameter

Description

szFullPath

The full path of the file to open.

hWnd

Handle for the window in which the file is displayed.

openFlags

Type of window view. Must be one of the following: AV_EXTERNAL_VIEW: Display the AVPageView, scrollbars, toolbar, and bookmark or thumbnails pane. Annotations are active. AV_DOC_VIEW: Display the AVPageView, scrollbars, and bookmark or thumbnails pane. Annotations are active. AV_PAGE_VIEW: Display only the AVPageView (the window that displays the PDF file). Do not display scrollbars, the toolbar, and bookmark or thumbnails pane. Annotations are active. - Use either AV_DOC_VIEW or AV_PAGE_VIEW whenever possible. Use AV_EXTERNAL_VIEW only if you do not want the application to display its own toolbar. Use AV_PAGE_VIEW to open the file with no scrollbars and no status window at the bottom of the page.

useOpenParams

0 indicates that the open action of the file is used; a positive number indicates that the action is overridden with the parameters that follow.

pgNum

Page number at which the file is to be opened if useOpenParams is a positive number. The first page is zero.

pageMode

Specifies page view mode if useOpenParams is a positive number. Possible values: PDDontCare: 0: leave the view mode as it is PDUseNone: 1: display without bookmarks or thumbnails PDUseThumbs: 2: display using thumbnails PDUseBookmarks: 3: display using bookmarks PDFullScreen: 4: display in full screen mode

zoomType

Zoom type of the page view if useOpenParams is a positive number. Possible values are: AVZoomFitHeight: Fits the page’s height in the window. AVZoomFitPage: Fits the page in the window. AVZoomFitVisibleWidth: Fits the page’s visible content into the window. AVZoomFitWidth: Fits the page’s width into the window. AVZoomNoVary: A fixed zoom, such as 100%.

zoom

Zoom factor, used only for AVZoomNoVary if useOpenParams is a positive number.

top

Used for certain zoom types (such as AVZoomNoVary) if useOpenParams is a positive number. See the PDF Reference for information on views.

left

Used for certain zoom types (such as AVZoomNoVary) if useOpenParams is a positive number. See the PDF Reference for information on views.

Returns

-1 if the document was opened successfully, 0 otherwise.

PrintPages

Prints a specified range of pages displaying a print progress dialog box. PrintPages always uses the default printer setting. It is possible to create custom dialog boxes as shown in the ActiveViewVB sample. Such custom dialog boxes could be used in place of the print progress dialog box or any other dialog box.

Syntax

VARIANT_BOOL PrintPages(long nFirstPage,
                 long nLastPage,long nPSLevel,

                 long bBinaryOk, long bShrinkToFit);

Parameters

Parameter

Description

nFirstPage

The first page to be printed. The first page in a PDDoc object is page 0.

nLastPage

The last page to be printed.

nPSLevel

Valid values are 2 and 3. If 2, PostScript Level 2 operators are used. If 3, PostScript Language Level 3 operators are also used.

bBinaryOk

If a positive number, binary data can be included in the PostScript program. If 0, all data is encoded as 7-bit ASCII.

bShrinkToFit

If a positive number, the page is shrunk (if necessary) to fit within the imageable area of the printed page. If 0, it is not.

Returns

0 if there were any exceptions while printing or if no document was open, -1 otherwise.

PrintPagesEx

Prints a specified range of pages, displaying a print progress dialog box. PrintPagesEx has more parameters than PrintPages. PrintPagesEx always uses the default printer setting. It is possible to create custom dialog boxes as shown in the ActiveViewVB sample. Such custom dialog boxes could be used in place of the print progress dialog box or any other dialog box.

Syntax

VARIANT_BOOL printPagesEx(long nFirstPage,long nLastPage,
                 long nPSLevel, long bBinaryOk,

                 long bShrinkToFit, long bReverse,

                 long bFarEastFontOpt, long bEmitHalftones,

                 long iPageOption);

Parameters

Parameter

Description

nFirstPage

The first page to be printed. The first page in a PDDoc object is page 0.

nLastPage

The last page to be printed.

nPSLevel

If 2, PostScript Level 2 operators are used. If 3, PostScript Language Level 3 operators are also used.

bBinaryOk

If a positive number, binary data may be included in the PostScript program. If 0, all data is encoded as 7-bit ASCII.

bShrinkToFit

If a positive number, the page is shrunk (if necessary) to fit within the imageable area of the printed page. If 0, it is not.

bReverse

(PostScript printing only) If a positive number, print the pages in reverse order. If false, print the pages in the regular order.

bFarEastFontOpt

(PostScript printing only) Set to a positive number if the destination printer has multibyte fonts; set to 0 otherwise.

bEmitHalftones

(PostScript printing only) If a positive number, emit the halftones specified in the document. If 0, do not.

iPageOption

Pages in the range to print. Must be one of: PDAllPages, PDEvenPagesOnly, or PDOddPagesOnly.

Returns

0 if there were any exceptions while printing or if no document was open, -1 otherwise.

PrintPagesSilent

Prints a specified range of pages without displaying any dialog box. This method is identical to AVDoc. PrintPages except for not displaying the dialog box. PrintPagesSilent always uses the default printer setting.

Syntax

VARIANT_BOOL PrintPagesSilent(long nFirstPage, long nLastPage,

                 long nPSLevel, long bBinaryOk,

                 long bShrinkToFit);

Parameters

Parameter

Description

nFirstPage

The first page to be printed. The first page in a PDDoc object is page 0.

nLastPage

The last page to be printed.

nPSLevel

If 2, PostScript Level 2 operators are used. If 3, PostScript Language Level 3 operators are also used.

bBinaryOk

If a positive number, binary data may be included in the PostScript program. If 0, all data is encoded as 7-bit ASCII.

bShrinkToFit

If a positive number, the page is shrunk (if necessary) to fit within the imageable area of the printed page. If 0, it is not.

Returns

0 if there were any exceptions while printing or if no document was open, -1 otherwise.

PrintPagesSilentEx

Prints a specified range of pages without displaying any dialog box. This method is identical to AVDoc. PrintPagesEx except for not displaying the dialog box. PrintPagesSilentEx has more parameters than PrintPagesSilent. PrintPagesSilentEx always uses the default printer setting.

Syntax

VARIANT_BOOL PrintPagesSilentEx(long nFirstPage,
                 long nLastPage,

                 long nPSLevel, long bBinaryOk,

                 long bShrinkToFit, long bReverse,

                 long bFarEastFontOpt,

                 long bEmitHalftones,

                 long iPageOption);

Parameters

Parameter

Description

nFirstPage

The first page to be printed.

nLastPage

The last page to be printed.

nPSLevel

If 2, PostScript Level 2 operators are used. If 3, PostScript Language Level 3 operators are also used.

bBinaryOk

If a positive number, binary data may be included in the PostScript program. If 0, all data is encoded as 7-bit ASCII.

bShrinkToFit

If a positive number, the page is shrunk (if necessary) to fit within the imageable area of the printed page. If 0, it is not.

bReverse

(PostScript printing only) If a positive number, print the pages in reverse order. If false, print the pages in the regular order.

bFarEastFontOpt

(PostScript printing only) Set to a positive number if the destination printer has multibyte fonts; set to 0 otherwise.

bEmitHalftones

(PostScript printing only) If a positive number, emit the halftones specified in the document. If 0, do not.

iPageOption

Pages in the range to print. Must be one of: PDAllPages, PDEvenPagesOnly, or PDOddPagesOnly.

Returns

0 if there were any exceptions while printing, -1 otherwise.

SetFrame

Sets the window’s size and location.

Syntax

VARIANT_BOOL SetFrame(LPDISPATCH iAcroRect);

Parameters

Parameter

Description

iAcroRect

The LPDISPATCH for an AcroExch.Rect specifying the window frame. iAcroRect's instance variable m_lpDispatch contains this LPDISPATCH.

Returns

Always returns -1.

SetTextSelection

Sets the document’s selection to the specified text selection. Before calling this method, use one of the following to create the text selection:

After calling this method, use AVDoc. ShowTextSelect to show the selection.

Syntax

VARIANT_BOOL SetTextSelection(LPDISPATCH iAcroPDTextSelect);

Parameters

Parameter

Description

iAcroPDTextSelect

The LPDISPATCH for the text selection to use. iAcroPDTextSelect contains the instance variable m_lpDispatch, which contains the LPDISPATCH.

Returns

Returns -1 if successful . Returns 0 if no document is open or the LPDISPATCH is not a PDTextSelect object.

SetTitle

Sets the window’s title.

Syntax

VARIANT_BOOL SetTitle(BSTR szTitle);

Parameters

Parameter

Description

szTitle

The title to be set. This method cannot be used for document windows, but only for windows created by Plugins.

Returns

Returns 0 if no document is open, -1 otherwise.

SetViewMode

Sets the mode in which the document will be viewed (pages only, pages and thumbnails, or pages and bookmarks).

Syntax

VARIANT_BOOL SetViewMode(long nType);

Parameters

Parameter

Description

nType

The view mode to be set. Possible values: PDDontCare: 0: leave the view mode as it is PDUseNone: 1: display without bookmarks or thumbnails PDUseThumbs: 2: display using thumbnails PDUseBookmarks: 3: display using bookmarks .. note:: Do not set the view mode to Close with AVDoc.SetViewMode when using AVDoc.OpenInWindowEx ; this will cause the viewer and application to hang.

Returns

0 if an error occurred while setting the view mode or if no document was open, -1 otherwise.

ShowTextSelect

Changes the view so that the current text selection is visible.

Syntax

VARIANT_BOOL ShowTextSelect();

Returns

Returns 0 if no document is open, -1 otherwise.

AcroExch.AVPageView

The area of the Acrobat application’s window that displays the contents of a document’s page. This is a non-creatable interface. Every AVDoc object has an AVPageView object and vice versa. The object provides access to the PDDoc and PDPage objects for the document being displayed.

Methods

The AVPageView object has the following methods.

Method

Description

DevicePointToPage

Converts the coordinates of a point from device space to user space.

DoGoBack

Goes to the previous view on the view history stack, if any.

DoGoForward

Goes to the next view on the view history stack, if any.

GetAperture

Gets the aperture of the specified page view.

GetAVDoc

Gets the AcroExch.AVDoc associated with the current page.

GetDoc

Gets the AcroExch.PDDoc corresponding to the current page.

GetPage

Gets the AcroExch.PDPage corresponding to the current page.

GetPageNum

Gets the page number of the current page.

GetZoom

Gets the current zoom factor, specified as a percent.

GetZoomType

Gets the current zoom type.

Goto

Goes to the specified page.

PointToDevice

Deprecated. Converts the coordinates of a point from user space to device space.

ReadPageDown

Scrolls forward through the document by one screen area.

ReadPageUp

Scrolls backward through the document by one screen area.

ScrollTo

Scrolls to the specified location on the current page.

ZoomTo

Zooms to the specified magnification.

DevicePointToPage

Converts the coordinates of a point from device space to user space.

Syntax

LPDISPATCH DevicePointToPage(LPDISPATCH iAcroPoint);

Parameters

Parameter

Description

iAcroPoint

The LPDISPATCH for the AcroExch.Point whose coordinates are converted. iAcroPoint contains the instance variable m_lpDispatch, which contains the LPDISPATCH.

Returns

The LPDISPATCH for an AcroExch.Point containing the converted coordinates.

DoGoBack

Goes to the previous view on the view history stack, if any.

Syntax

VARIANT_BOOL DoGoBack();

Returns

Always returns -1.

DoGoForward

Goes to the next view on the view history stack, if any.

Syntax

VARIANT_BOOL DoGoForward();

Returns

Always returns -1.

GetAperture

Gets the aperture of the specified page view. The aperture is the rectangular region of the window in which the document is drawn, measured in device space units.

Syntax

CAcroRect* GetAperture();

Returns

A pointer to the aperture rectangle. Its coordinates are specified in device space.

GetAVDoc

Gets the AcroExch.AVDoc associated with the current page.

Syntax

LPDISPATCH GetAVDoc();

Returns

The LPDISPATCH for the AcroExch.AVDoc.

GetDoc

Gets the AcroExch.PDDoc corresponding to the current page.

Syntax

LPDISPATCH GetDoc();

Returns

The LPDISPATCH for the AcroExch.PDDoc.

GetPage

Gets the AcroExch.PDPage corresponding to the current page.

Syntax

LPDISPATCH GetPage();

Returns

The LPDISPATCH for the AcroExch.PDPage.

GetPageNum

Gets the page number of the current page. The first page in a document is page zero.

Syntax

long GetPageNum();

Returns

The current page’s page number.

GetZoom

Gets the current zoom factor, specified as a percent. For example, 100 is returned if the magnification is 1.0.

Syntax

long GetZoom();

Returns

The current zoom factor.

GetZoomType

Gets the current zoom type.

Syntax

short GetZoomType();

Returns

Zoom type. The value is one of the following:

  • AVZoomFitHeight: Fits the page’s height in the window.

  • AVZoomFitPage: Fits the page in the window.

  • AVZoomFitVisibleWidth: Fits the page’s visible content into the window.

  • AVZoomFitWidth: Fits the page’s width into the window.

  • AVZoomNoVary: A fixed zoom, such as 100%.

Goto

Goes to the specified page.

Syntax

VARIANT_BOOL GoTo(long nPage);

Parameters

Parameter

Description

nPage

Page number of the destination page. The first page in a PDDoc object is page 0.

Returns

-1 if the Acrobat application successfully went to the page, 0 otherwise.

PointToDevice

Converts the coordinates of a point from user space to device space.

Note

Deprecated. Do not use this method.

Syntax

LPDISPATCH PointToDevice(LPDISPATCH iAcroPoint);

Parameters

Parameter

Description

iAcroPoint

The LPDISPATCH for the AcroExch.Point whose coordinates are converted. iAcroPoint contains the instance variable m_lpDispatch, which contains this LPDISPATCH.

Returns

The LPDISPATCH for an AcroExch.Point containing the converted coordinates.

ReadPageDown

Scrolls forward through the document by one screen area.

Syntax

VARIANT_BOOL ReadPageDown();

Returns

Always returns -1.

ReadPageUp

Scrolls backward through the document by one screen area.

Syntax

VARIANT_BOOL ReadPageUp();

Returns

Always returns -1.

ScrollTo

Scrolls to the specified location on the current page.

Syntax

VARIANT_BOOL ScrollTo(short nX, short nY);

Parameters

Parameter

Description

nX

The x–coordinate of the destination.

nY

The y–coordinate of the destination.

Returns

-1 if the Acrobat application successfully scrolled to the specified location, 0 otherwise.

ZoomTo

Zooms to the specified magnification.

Syntax

VARIANT_BOOL ZoomTo(short nType, short nScale);

Parameters

Parameter

Description

nType

Zoom type. Possible values are: AVZoomFitHeight: Fits the page’s height into the window. AVZoomFitPage: Fits the page into the window. AVZoomFitVisibleWidth: Fits the page’s visible content into the window. AVZoomFitWidth: Fits the page’s width into the window. AVZoomNoVary: A fixed zoom, such as 100%.

nScale

The desired zoom factor, expressed as a percentage. For example, 100 is a magnification of 1.0.

Returns

-1 if the magnification was set successfully, 0 otherwise.

AcroExch.HiliteList

A highlighted region of text in a PDF document, which may include one or more contiguous groups of characters or words on a single page. This is a creatable interface. This object has a single method, Add, and is used by the PDPage object to create PDTextSelect objects.

Add

Adds the highlight specified by nOffset and nLength to the current highlight list. Highlight lists are used to highlight one or more contiguous groups of characters or words on a single page.

Highlight lists are used both for character-based and word-based highlighting, although a single highlight list cannot contain a mixture of character and word highlights. After creating a highlight list, use PDPage. CreatePageHilite or PDPage. CreateWordHilite (depending on whether the highlight list is used for characters or words) to create a text selection from the highlight list.

Syntax

VARIANT_BOOL Add(short nOffset, short nLength);

Parameters

Parameter

Description

nOffset

Offset of the first word or character to be highlighted, the first of which has an offset of zero.

nLength

The number of consecutive words or characters to be highlighted.

Returns

Always returns -1.

AcroExch.PDAnnot

An annotation on a page in a PDF file. This is a non-creatable interface. Acrobat applications have two built-in annotation types: PDTextAnnot and PDLinkAnnot. The object provides access to the physical attributes of the annotation. Plugins may add movie and Widget (form field) annotations, and developers can define new annotation subtypes by creating new annotation handlers.

Methods

The PDAnnot object has the following methods.

Method

Description

GetColor

Gets an annotation’s color.

GetContents

Gets a text annotation’s contents.

GetDate

Gets an annotation’s date.

GetRect

Gets an annotation’s bounding rectangle.

GetSubtype

Gets an annotation’s subtype.

GetTitle

Gets a text annotation’s title.

IsEqual

Determines whether an annotation is the same as the specified annotation.

IsOpen

Tests whether a text annotation is open.

IsValid

Tests whether an annotation is still valid.

Perform

Performs a link annotation’s action.

SetColor

Sets an annotation’s color.

SetContents

Sets a text annotation’s contents.

SetDate

Sets an annotation’s date.

SetOpen

Opens or closes a text annotation.

SetRect

Sets an annotation’s bounding rectangle.

SetTitle

Sets a text annotation’s title.

GetColor

Gets an annotation’s color.

Syntax

long GetColor();

Returns

The annotation’s color, a long value of the form 0x00BBGGRR where the first byte from the right (RR) is a relative value for red, the second byte (GG) is a relative value for green, and the third byte (BB) is a relative value for blue. The high-order byte must be 0.

GetContents

Gets a text annotation’s contents.

Syntax

BSTR GetContents();

Returns

The annotation’s contents.

GetDate

Gets an annotation’s date.

Syntax

LPDISPATCH GetDate();

Returns

The LPDISPATCH for an AcroExch.Time object containing the date.

GetRect

Gets an annotation’s bounding rectangle.

Syntax

LPDISPATCH GetRect();

Returns

The LPDISPATCH for an AcroExch.Rect containing the annotation’s bounding rectangle.

GetSubtype

Gets an annotation’s subtype.

Syntax

BSTR GetSubtype();

Returns

The annotation’s subtype. The built-in subtypes are Text and Link.

GetTitle

Gets a text annotation’s title.

Syntax

BSTR GetTitle();

Returns

The annotation’s title.

IsEqual

Determines whether an annotation is the same as the specified annotation.

Syntax

VARIANT_BOOL IsEqual(LPDISPATCH PDAnnot);

Parameters

Parameter

Description

PDAnnot

The LPDISPATCH for the AcroExch.PDAnnot to be tested. PDAnnot contains the instance variable m_lpDispatch, which contains the LPDISPATCH.

Returns

-1 if the annotations are the same, 0 otherwise.

IsOpen

Tests whether a text annotation is open.

Syntax

VARIANT_BOOL IsOpen();

Returns

-1 if open, 0 otherwise.

IsValid

Tests whether an annotation is still valid. This method is intended only to test whether the annotation has been deleted, not whether it is a completely valid annotation object.

Syntax

VARIANT_BOOL IsValid();

Returns

-1 if the annotation is valid, 0 otherwise.

Perform

Performs a link annotation’s action.

Syntax

VARIANT_BOOL Perform(LPDISPATCH iAcroAVDoc);

Parameters

Parameter

Description

iAcroAVDoc

The LPDISPATCH for the AcroExch.AVDoc in which the annotation is located. iAcroAVDoc contains the instance variable m_lpDispatch, which contains the LPDISPATCH.

Returns

-1 if the action was executed successfully, 0 otherwise.

SetColor

Sets an annotation’s color.

Syntax

VARIANT_BOOL SetColor(long nRGBColor);

Parameters

Parameter

Description

nRGBColor

The color to use for the annotation.

Returns

-1 if the annotation’s color was set, 0 if the Acrobat application does not support editing.

nRGBColor is a long value with the form 0x00BBGGRR where the first byte from the right (RR) is a relative value for red, the second byte (GG) is a relative value for green, and the third byte (BB) is a relative value for blue. The high-order byte must be 0.

SetContents

Sets a text annotation’s contents.

Syntax

VARIANT_BOOL SetContents(BSTR szContents);

Parameters

Parameter

Description

szContents

The contents to use for the annotation.

Returns

0 if the Acrobat application does not support editing, -1 otherwise.

SetDate

Sets an annotation’s date.

Syntax

VARIANT_BOOL SetDate(LPDISPATCH iAcroTime);

Parameters

Parameter

Description

iAcroTime

The LPDISPATCH for the date and time to use for the annotation. iAcroTime's instance variable m_lpDispatch contains this LPDISPATCH.

Returns

-1 if the date was set, 0 if the Acrobat application does not support editing.

SetOpen

Opens or closes a text annotation.

Syntax

VARIANT_BOOL SetOpen(long bIsOpen);

Parameters

Parameter

Description

bIsOpen

If a positive number, the annotation is open. If 0, the annotation is closed.

Returns

Always returns -1.

SetRect

Sets an annotation’s bounding rectangle.

Syntax

VARIANT_BOOL SetRect(LPDISPATCH iAcroRect);

Parameters

Parameter

Description

iAcroRect

The LPDISPATCH for the bounding rectangle (AcroExch.Rect) to set. iAcroRect contains the instance variable m_lpDispatch, which contains the LPDISPATCH.

Returns

-1 if a rectangle was supplied, 0 otherwise.

SetTitle

Sets a text annotation’s title.

Syntax

VARIANT_BOOL SetTitle(BSTR szTitle);

Parameters

Parameter

Description

szTitle

The title to use.

Returns

-1 if the title was set, 0 if the Acrobat application does not support editing.

AcroExch.PDBookmark

A bookmark for a page in a PDF file. This is a creatable interface. Each bookmark has a title that appears on screen, and an action that specifies what happens when a user clicks on the bookmark.

Bookmarks can either be created interactively by the user through the Acrobat application’s user interface or programmatically generated. The typical action for a user-created bookmark is to move to another location in the current document, although any action can be specified. It is not possible to create a bookmark with OLE—only to destroy one.

Methods

The PDBookmark object has the following methods.

Method

Description

Destroy

Destroys a bookmark.

GetByTitle

Gets the bookmark that has the specified title.

GetTitle

Gets a bookmark’s title.

IsValid

Determines whether the bookmark is valid.

Perform

Performs a bookmark’s action.

SetTitle

Sets a bookmark’s title.

Destroy

Destroys a bookmark.

Syntax

VARIANT_BOOL Destroy();

Returns

0 if the Acrobat application does not support editing (making it impossible to delete the bookmark), -1 otherwise.

GetByTitle

Gets the bookmark that has the specified title. The AcroExch.PDBookmark object is set to the specified bookmark as a side effect of the method; it is not the method’s return value. You cannot enumerate bookmark titles with this method.

Syntax

VARIANT_BOOL GetByTitle(LPDISPATCH iAcroPDDoc,
                 BSTR bookmarkTitle);

Parameters

Parameter

Description

iAcroPDDoc

The LPDISPATCH for the document (AcroExch.PDDoc object) containing the bookmark. iAcroPDDoc contains the instance variable m_lpDispatch, which contains the LPDISPATCH.

bookmarkTitle

The title of the bookmark to get. The capitalization of the title must match that in the bookmark.

Returns

  • -1 if the specified bookmark exists (the method determines this using the PDBookmark. IsValid method), 0 otherwise.

Example

CAcroPDBookmark* bookmark = new CAcroPDBookmark;

bookmark->CreateDispatch("AcroExch.PDBookmark");

bookmark->GetByTitle(m_pAcroAVDoc->GetPDDoc(), "Name of Bookmark");

if (bookmark->IsValid())
    bookmark->Perform(m_pAcroAVDoc->m_lpDispatch);
else
    AfxMessageBox("Bookmark not valid");

GetTitle

Gets a bookmark’s title.

Syntax

BSTR GetTitle();

Returns

The title.

IsValid

Determines whether the bookmark is valid. This method only checks whether the bookmark has been deleted; it does not thoroughly check the bookmark’s data structures.

Syntax

VARIANT_BOOL IsValid();

Returns

-1 if the bookmark is valid, 0 otherwise.

Syntax

Perform

Performs a bookmark’s action.

Syntax

VARIANT_BOOL Perform(LPDISPATCH iAcroAVDoc);

Parameters

Parameter

Description

iAcroAVDoc

The LPDISPATCH for the AcroExch.AVDoc in which the bookmark is located. iAcroAVDoc contains the instance variable m_lpDispatch, which contains the LPDISPATCH.

Returns

-1 if the action was executed successfully, 0 otherwise.

SetTitle

Sets a bookmark’s title.

Syntax

VARIANT_BOOL SetTitle(BSTR szNewTitle);

Parameters

Parameter

Description

szNewTitle

The title to set.

Returns

0 if the Acrobat application does not support editing, -1 otherwise.

AcroExch.PDDoc

The underlying PDF representation of a document. This is a creatable interface. There is a correspondence between a PDDoc object and an ASFile object (an opaque representation of an open file made available through an interface encapsulating Acrobat’s access to file services), and the PDDoc object is the hidden object behind every AVDoc object. An ASFile object may have zero or more underlying files, so a PDF file does not always correspond to a single disk file. For example, an ASFile object may provide access to PDF data in a database.

Through PDDoc objects, your application can perform most of the Document menu items from Acrobat (delete pages, replace pages, and so on), create and delete thumbnails, and set and retrieve document information fields.

Methods

The PDDoc object has the following methods.

Method

Description

AcquirePage

Acquires the specified page.

ClearFlags

Clears a document’s flags.

Close

Closes a file.

Create

Creates a new AcroExch.PDDoc.

CreateTextSelect

Creates a text selection from the specified rectangle on the specified page.

CreateThumbs

Creates thumbnail images for the specified page range in a document.

CropPages

Crops the pages in a specified range in a document.

DeletePages

Deletes pages from a file.

DeleteThumbs

Deletes thumbnail images from the specified pages in a document.

GetFileName

Gets the name of the file associated with this AcroExch.PDDoc.

GetFlags

Gets a document’s flags.

GetInfo

Gets the value of a specified key in the document’s Info dictionary.

GetInstanceID

Gets the instance ID (the second element) from the ID array in the document’s trailer.

GetJSObject

Gets a dual interface to the JavaScript object associated with the PDDoc.

GetNumPages

Gets the number of pages in a file.

GetPageMode

Gets a value indicating whether the Acrobat application is currently displaying only pages, pages and thumbnails, or pages and bookmarks.

GetPermanentID

Gets the permanent ID (the first element) from the ID array in the document’s trailer.

InsertPages

Inserts the specified pages from the source document after the indicated page within the current document.

MovePage

Moves a page to another location within the same document.

Open

Opens a file.

OpenAVDoc

Opens a window and displays the document in it.

ReplacePages

Replaces the indicated pages in the current document with those specified from the source document.

Save

Saves a document.

SetFlags

Sets a document’s flags indicating whether the document has been modified, whether the document is a temporary document and should be deleted when closed, and the version of PDF used in the file.

SetInfo

Sets the value of a key in a document’s Info dictionary.

SetPageMode

Sets the page mode in which a document is to be opened: display only pages, pages and thumbnails, or pages and bookmarks.

AcquirePage

Acquires the specified page.

Syntax

LPDISPATCH AcquirePage(long nPage);

Parameters

Parameter

Description

nPage

The number of the page to acquire. The first page is page 0.

Returns

The LPDISPATCH for the AcroExch.PDPage object for the acquired page . Returns NULL if the page could not be acquired.

ClearFlags

Clears a document’s flags. The flags indicate whether the document has been modified, whether the document is a temporary document and should be deleted when closed, and the version of PDF used in the file. This method can be used only to clear, not to set, the flag bits.

Syntax

VARIANT_BOOL ClearFlags(long nFlags);

Parameters

Parameter

Description

nFlags

Flags to be cleared. See PDDoc. GetFlags for a description of the flags. The flags PDDocWasRepaired , PDDocNewMajorVersion , PDDocNewMinorVersion , and PDDocOldVersion are read-only and cannot be cleared.

Returns

Always returns -1.

Close

Closes a file.

Note

If PDDoc and AVDoc are constructed with the same file, PDDoc.Close destroys both objects (which closes the document in the viewer).

Syntax

VARIANT_BOOL Close();

Returns

-1 if the document was closed successfully, 0 otherwise.

Create

Creates a new AcroExch.PDDoc.

Syntax

VARIANT_BOOL Create();

Returns

-1 if the document is created successfully, 0 if it is not or if the Acrobat application does not support editing.

CreateTextSelect

Creates a text selection from the specified rectangle on the specified page. After creating the text selection, use the AVDoc. SetTextSelection method to use it as the document’s selection, and use AVDoc. ShowTextSelect to show the selection.

Syntax

LPDISPATCH CreateTextSelect(long nPage, LPDISPATCH iAcroRect);

Parameters

Parameter

Description

nPage

The page on which the selection is created. The first page in a PDDoc object is page 0.

iAcroRect

The LPDISPATCH for the AcroExch.Rect enclosing the region to select. iAcroRect contains the instance variable m_lpDispatch, which contains the LPDISPATCH.

Returns

The LPDISPATCH for an AcroExch.PDTextSelect containing the text selection . Returns NULL if the text selection was not created successfully.

CreateThumbs

Creates thumbnail images for the specified page range in a document.

Syntax

VARIANT_BOOL CreateThumbs(long nFirstPage, long nLastPage);

Parameters

Parameter

Description

nFirstPage

First page for which thumbnail images are created. The first page in a PDDoc object is page 0.

nLastPage

Last page for which thumbnail images are created.

Returns

-1 if thumbnail images were created successfully, 0 if they were not or if the Acrobat application does not support editing.

CropPages

Crops the pages in a specified range in a document. This method ignores the request if either the width or height of the crop box is less than 72 points (one inch).

Syntax

VARIANT_BOOL CropPages(long nStartPage, long nEndPage,

                 short nEvenOrOddPagesOnly,

                 LPDISPATCH iAcroRect);

Parameters

Parameter

Description

nStartPage

First page that is cropped. The first page in a PDDoc object is page 0.

nEndPage

Last page that is cropped.

nEvenOrOddPagesOnly

Value indicating which pages in the range are cropped. Must be one of the following: 0: crop all pages in the range 1: crop only odd pages in the range 2: crop only even pages in the range

iAcroRect

An LPDISPATCH for a CAcroRect specifying the cropping rectangle, which is specified in user space.

Returns

-1 if the pages were cropped successfully, 0 otherwise.

DeletePages

Deletes pages from a file.

Syntax

VARIANT_BOOL DeletePages(long nStartPage, long nEndPage);

Parameters

Parameter

Description

nStartPage

The first page to be deleted. The first page in a PDDoc object is page 0.

nEndPage

The last page to be deleted.

Returns

-1 if the pages were successfully deleted . Returns 0 if they were not or if the Acrobat application does not support editing.

DeleteThumbs

Deletes thumbnail images from the specified pages in a document.

Syntax

VARIANT_BOOL DeleteThumbs(long nStartPage, long nEndPage);

Parameters

Parameter

Description

nStartPage

First page whose thumbnail image is deleted. The first page in a PDDoc object is page 0.

nEndPage

Last page whose thumbnail image is deleted.

Returns

-1 if the thumbnails were deleted, 0 if they were not deleted or if the Acrobat application does not support editing.

GetFileName

Gets the name of the file associated with this AcroExch.PDDoc.

Syntax

BSTR GetFileName();

Returns

The file name, which can currently contain up to 256 characters.

GetFlags

Gets a document’s flags. The flags indicate whether the document has been modified, whether the document is a temporary document and should be deleted when closed, and the version of PDF used in the file.

Syntax

long GetFlags();

Returns

The document’s flags, containing an OR of the following:

Flag

Description

PDDocNeedsSave

Document has been modified and needs to be saved.

PDDocRequiresFullSave

Document cannot be saved incrementally; it must be written using PDSaveFull.

PDDocIsModified

Document has been modified slightly (such as bookmarks or text annotations have been opened or closed), but not in a way that warrants saving.

PDDocDeleteOnClose

Document is based on a temporary file that must be deleted when the document is closed or saved.

PDDocWasRepaired

Document was repaired when it was opened.

PDDocNewMajorVersion

Document’s major version is newer than current.

PDDocNewMinorVersion

Document’s minor version is newer than current.

PDDocOldVersion

Document’s version is older than current.

PDDocSuppressErrors

Don’t display errors.

GetInfo

Gets the value of a specified key in the document’s Info dictionary. A maximum of 512 bytes are returned.

Syntax

BSTR GetInfo(BSTR szInfoKey);

Parameters

Parameter

Description

szInfoKey

The key whose value is obtained.

Returns

The string if the value was read successfully . Returns an empty string if the key does not exist or its value cannot be read.

GetInstanceID

Gets the instance ID (the second element) from the ID array in the document’s trailer.

Syntax

BSTR GetInstanceID();

Returns

A string whose maximum length is 32 characters, containing the document’s instance ID.

GetJSObject

Gets a dual interface to the JavaScript object associated with the PDDoc. This allows automation clients full access to both built-in and user-defined JavaScript methods available in the document.

Syntax

LDispatch* GetJSObject();

Returns

The interface to the JavaScript object if the call succeeded, NULL otherwise.

GetNumPages

Gets the number of pages in a file.

Syntax

long GetNumPages();

Returns

The number of pages, or -1 if the number of pages cannot be determined.

GetPageMode

Gets a value indicating whether the Acrobat application is currently displaying only pages, pages and thumbnails, or pages and bookmarks.

Syntax

long GetPageMode();

Returns

The current page mode. Will be one of the following values:

  • PDDontCare: 0: leave the view mode as it is

  • PDUseNone: 1: display without bookmarks or thumbnails

  • PDUseThumbs: 2: display using thumbnails

  • PDUseBookmarks: 3: display using bookmarks

  • PDFullScreen: 4: display in full screen mode

GetPermanentID

Gets the permanent ID (the first element) from the ID array in the document’s trailer.

Syntax

BSTR GetPermanentID();

Returns

A string whose maximum length is 32 characters, containing the document’s permanent ID.

InsertPages

Inserts the specified pages from the source document after the indicated page within the current document.

Syntax

VARIANT_BOOL InsertPages(long nInsertPageAfter,
                 LPDISPATCH iPDDocSource,long nStartPage,
                 long nNumPages, long bBookmarks);

Parameters

Parameter

Description

nInsertPageAfter

The page in the current document after which pages from the source document are inserted. The first page in a PDDoc object is page 0.

iPDDocSource

The LPDISPATCH for the AcroExch.PDDoc containing the pages to insert. iPDDocSource contains the instance variable m_lpDispatch, which contains the LPDISPATCH.

nStartPage

The first page in iPDDocSource to be inserted into the current document.

nNumPages

The number of pages to be inserted.

bBookmarks

If a positive number, bookmarks are copied from the source document. If 0, they are not.

Returns

-1 if the pages were successfully inserted . Returns 0 if they were not or if the Acrobat application does not support editing.

MovePage

Moves a page to another location within the same document.

Syntax

VARIANT_BOOL MovePage(long nMoveAfterThisPage,
                 long nPageToMove);

Parameters

Parameter

Description

nMoveAfterThisPage

The page being moved is placed after this page number. The first page in a PDDoc object is page 0.

nPageToMove

Page number of the page to be moved.

Returns

0 if the Acrobat application does not support editing, -1 otherwise.

Open

Opens a file. A new instance of AcroExch.PDDoc must be created for each open PDF file.

Syntax

VARIANT_BOOL Open(BSTR szFullPath);

Parameters

Parameter

Description

szFullPath

Full path of the file to be opened.

Returns

-1 if the document was opened successfully, 0 otherwise.

OpenAVDoc

Opens a window and displays the document in it.

Syntax

LPDISPATCH OpenAVDoc(BSTR szTitle);

Parameters

Parameter

Description

szTitle

The title to be used for the window. A default title is used if szTitle is NULL or an empty string.

Returns

The LPDISPATCH for the AcroExch.AVDoc that was opened, or NULL if the open fails.

ReplacePages

Replaces the indicated pages in the current document with those specified from the source document. No links or bookmarks are copied from iPDDocSource, but text annotations may optionally be copied.

Syntax

VARIANT_BOOL ReplacePages(long nStartPage,
                 LPDISPATCH iPDDocSource,

                 long nStartSourcePage, long nNumPages,

                 long bMergeTextAnnotations);

Parameters

Parameter

Description

nStartPage

The first page within the source file to be replaced. The first page in a PDDoc object is page 0.

iPDDocSource

The LPDISPATCH for the AcroExch.PDDoc containing the new copies of pages that are replaced. iPDDocSource contains the instance variable m_lpDispatch, which contains the LPDISPATCH.

nStartSourcePage

The first page in iPDDocSource to use as a replacement page.

nNumPages

The number of pages to be replaced.

bMergeTextAnnotations

If a positive number, text annotations from iPDDocSource are copied. If 0, they are not.

Returns

-1 if the pages were successfully replaced . Returns 0 if they were not or if the Acrobat application does not support editing.

Save

Saves a document.

Syntax

VARIANT_BOOL Save(short nType, BSTR szFullPath);

Parameters

Parameter

Description

nType

Specifies the way in which the file should be saved. nType is a logical OR of one or more of the following flags: PDSaveIncremental: Write changes only, not the complete file. This will always result in a larger file, even if objects have been deleted. PDSaveFull: Write the entire file to the filename specified by szFullPath. PDSaveCopy: Write a copy of the file into the file specified by szFullPath, but keep using the old file. This flag can only be specified if PDSaveFull is also used. PDSaveCollectGarbage: Remove unreferenced objects; this often reduces the file size, and its usage is encouraged. This flag can only be specified if PDSaveFull is also used. PDSaveLinearized: Save the file optimized for the web, providing hint tables. This allows the PDF file to be byte-served. This flag can only be specified if PDSaveFull is also used. - If you save a file optimized for the web using the PDSaveLinearized flag, you must follow this sequence: 1. Open the PDF file with PDDoc. Open. 2. Call PDDoc. Save using the PDSaveLinearized flag. 3. Call PDDoc. Close. This allows batch optimization of files.

szFullPath

The new path to the file, if any.

Returns

-1 if the document was successfully saved . Returns 0 if it was not or if the Acrobat application does not support editing.

SetFlags

Sets a document’s flags indicating whether the document has been modified, whether the document is a temporary document and should be deleted when closed, and the version of PDF used in the file. This method can be used only to set, not to clear, the flag bits.

Syntax

VARIANT_BOOL SetFlags(long nFlags);

Parameters

Parameter

Description

nFlags

Flags to be set. See PDDoc. GetFlags for a description of the flags. The flags PDDocWasRepaired , PDDocNewMajorVersion , PDDocNewMinorVersion , and PDDocOldVersion are read-only and cannot be set.

Returns

Always returns -1.

SetInfo

Sets the value of a key in a document’s Info dictionary.

Syntax

VARIANT_BOOL SetInfo(BSTR szInfoKey, BSTR szBuffer);

Parameters

Parameter

Description

szInfoKey

The key whose value is set.

szBuffer

The value to be assigned to the key.

Returns

-1 if the value was added successfully, 0 if it was not or if the Acrobat application does not support editing.

">

SetPageMode

Sets the page mode in which a document is to be opened: display only pages, pages and thumbnails, or pages and bookmarks.

Syntax

VARIANT_BOOL SetPageMode(long nPageMode);

Parameters

Parameter

Description

nPageMode

The page mode to be set. Possible values: PDDontCare: 0: leave the view mode as it is PDUseNone: 1: display without bookmarks or thumbnails PDUseThumbs: 2: display using thumbnails PDUseBookmarks: 3: display using bookmarks

Returns

Always returns -1.

AcroExch.PDPage

A single page in the PDF representation of a document. This is a non-creatable interface. Just as PDF files are partially composed of their pages, PDDoc objects are composed of PDPage objects. A page contains a series of objects representing the objects drawn on the page (PDGraphic objects), a list of resources used in drawing the page, annotations (PDAnnot objects), an optional thumbnail image of the page, and the threads used in any articles that occur on the page. The first page in a PDDoc object is page 0.

Methods

The PDPage object has the following methods.

Method

Description

AddAnnot

Adds a specified annotation at a specified location in the page’s annotation array

AddNewAnnot

Creates a new text annotation and adds it to the page.

CopyToClipboard

Copies a PDF image to the clipboard without requiring an hWnd or hDC from the client.

CreatePageHilite

Creates a text selection from a list of character offsets and character counts on a single page.

CreateWordHilite

Creates a text selection from a list of word offsets and word counts on a single page.

CropPage

Crops the page.

Draw

Deprecated. Draws page contents into a specified window.

DrawEx

Draws page contents into a specified window.

GetAnnot

Gets the specified annotation from the page’s array of annotations.

GetAnnotIndex

Gets the index (within the page’s annotation array) of the specified annotation.

GetDoc

Gets the AcroExch.PDDoc associated with the page.

GetNumAnnots

Gets the number of annotations on the page.

GetNumber

Gets the page number of the current page. The first page in a document is page zero.

GetRotate

Gets the rotation value, in degrees, for the current page.

GetSize

Gets a page’s width and height in points.

RemoveAnnot

Removes the specified annotation from the page’s annotation array.

SetRotate

Sets the rotation, in degrees, for the current page.

AddAnnot

Adds a specified annotation at a specified location in the page’s annotation array.

Syntax

VARIANT_BOOL AddAnnot(long nIndexAddAfter,
                 LPDISPATCH iPDAnnot);

Parameters

Parameter

Description

nIndexAddAfter

Location in the page’s annotation array to add the annotation. The first annotation on a page has an index of zero.

iPDAnnot

The LPDISPATCH for the AcroExch.PDAnnot to add. iPDAnnot contains the instance variable m_lpDispatch, which contains the LPDISPATCH.

Returns

0 if the Acrobat application does not support editing, -1 otherwise.

AddNewAnnot

Creates a new text annotation and adds it to the page.

The newly-created text annotation is not complete until PDAnnot. SetContents has been called to fill in the /Contents key.

Syntax

LPDISPATCH AddNewAnnot(long nIndexAddAfter, BSTR szSubType,

                 LPDISPATCH iAcroRect);

Parameters

Parameter

Description

nIndexAddAfter

Location in the page’s annotation array after which to add the annotation. The first annotation on a page has an index of zero.

szSubType

Subtype of the annotation to be created. Must be text.

iAcroRect

The LPDISPATCH for the AcroExch.Rect bounding the annotation’s location on the page. iAcroRect contains the instance variable m_lpDispatch, which contains the LPDISPATCH.

Returns

The LPDISPATCH for an AcroExch.PDAnnot object, or NULL if the annotation could not be added.

CopyToClipboard

Copies a PDF image to the clipboard without requiring an hWnd or hDC from the client. This method is only available on 32-bit systems.

Syntax

VARIANT_BOOL CopyToClipboard(LPDISPATCH boundRect,
                 short nXOrigin,short nYOrigin,
                 short nZoom);

Parameters

Parameter

Description

boundRect

The LPDISPATCH for the AcroExch.Rect bounding rectangle in device space coordinates. boundRect contains the instance variable m_lpDispatch, which contains the LPDISPATCH.

nXOrigin

The x–coordinate of the portion of the page to be copied.

nYOrigin

The y–coordinate of the portion of the page to be copied.

nZoom

Zoom factor at which the page is copied, specified as a percent. For example, 100 corresponds to a magnification of 1.0.

Returns

-1 if the page is successfully copied, 0 otherwise.

CreatePageHilite

Creates a text selection from a list of character offsets and character counts on a single page. The text selection can then be set as the current selection using AVDoc. SetTextSelection , and the view can be set to show the selection using AVDoc. ShowTextSelect.

Syntax

LPDISPATCH CreatePageHilite(LPDISPATCH iAcroHiliteList);

Parameters

Parameter

Description

iAcroHiliteList

The LPDISPATCH for the highlight list for which a text selection is created. iAcroHiliteList contains the instance variable m_lpDispatch, which contains the LPDISPATCH. Use HiliteList. Add to create a highlight list.

Returns

The LPDISPATCH for the AcroExch.PDTextSelect containing the text selection, or NULL if the selection could not be created.

CreateWordHilite

Creates a text selection from a list of word offsets and word counts on a single page. The text selection can then be set as the current selection using AVDoc. SetTextSelection , and the view can be set to show the selection using AVDoc. ShowTextSelect.

Syntax

LPDISPATCH CreateWordHilite(LPDISPATCH iAcroHiliteList);

Parameters

Parameter

Description

iAcroHiliteList

The LPDISPATCH for the highlight list for which a text selection is created. iAcroHiliteList contains the instance variable m_lpDispatch, which contains the LPDISPATCH. Use HiliteList. Add to create a highlight list.

Returns

The LPDISPATCH for the AcroExch.PDTextSelect, or NULL if the selection could not be created.

CropPage

Crops the page. This method ignores the request if either the width or height of the crop box is less than 72 points (one inch).

Syntax

VARIANT_BOOL CropPage(LPDISPATCH iAcroRect);

Parameters

Parameter

Description

iAcroRect

An LPDISPATCH for a CAcroRect specifying the cropping rectangle, which is specified in user space.

Returns

-1 if the page was cropped successfully, 0 otherwise.

Draw

Note

Deprecated. As of Acrobat 3.0, this method simply returns false. Use the method AVDoc. DrawEx instead.

Syntax

VARIANT_BOOL Draw(short window, short displayContext,
                 short XOrigin,short YOrigin, short zoom);

Parameters

Parameter

Description

window

HWND into which the page is to be drawn.

displayContext

hDC to use for drawing. If NULL, the HDC for window is used. displayContext cannot be reliably used as the hDC for a printer device. In particular, Visual Basic applications cannot use Draw to print.

XOrigin

The x–coordinate of the portion of the page to be drawn.

YOrigin

The y–coordinate of the portion of the page to be drawn.

zoom

Zoom factor at which the page is to be drawn, specified as a percent. For example, 100 corresponds to a magnification of 1.0.

Returns

-1 if the page is successfully drawn, 0 otherwise.

DrawEx

Draws page contents into a specified window.

You can use PDPage. CopyToClipboard to copy page contents to the clipboard without an hWnd or hDC from the client.

Syntax

VARIANT_BOOL DrawEx(long window, long displayContext,

                 LPDISPATCH updateRect, short xOrigin,

                 short yOrigin, short zoom);

Parameters

Parameter

Description

window

Handle for the window (HWND) into which the page is drawn.

displayContext

This parameter is invalid; do not use it. Assign it a NULL value. If it is not assigned NULL, an exception is thrown. - displayContext cannot be reliably used as the hDC for a printer device. In particular, Visual Basic applications cannot use DrawEx to print.

updateRect

LPDISPATCH for an AcroExch.Rect to be drawn with user space coordinates. updateRect contains the instance variable m_lpDispatch, which contains the LPDISPATCH. Any objects outside of updateRect are not drawn. All objects are drawn if updateRect is NULL. Use methods in the CAcroRect class to set the size of the rectangle. For example:

CAcroRect* rect = new CAcroRect;
rect->CreateDispatch("AcroExch.Rect", &e);
   if (rect) { /* Set values for rect - increases from right to left and bottom to top */
   rect->SetLeft(100);
   rect->SetTop(400);
   rect->SetRight(400);
   rect->SetBottom(100); }

xOrigin

The x–coordinate of the portion of the page to be drawn.

yOrigin

The y–coordinate of the portion of the page to be drawn.

zoom

Zoom factor at which the page is drawn, specified as a percent. For example, 100 corresponds to a magnification of 1.0.

Returns

A positive number if the page is successfully drawn, 0 otherwise.

GetAnnot

Gets the specified annotation from the page’s array of annotations.

Syntax

LPDISPATCH GetAnnot(long nIndex);

Parameters

Parameter

Description

nIndex

Index (in the page’s annotation array) of the annotation to be retrieved. The first annotation in the array has an index of zero.

Returns

The LPDISPATCH for the AcroExch.PDAnnot object.

GetAnnotIndex

Gets the index (within the page’s annotation array) of the specified annotation.

Syntax

long GetAnnotIndex(LPDISPATCH iPDAnnot);

Parameters

Parameter

Description

iPDAnnot

LPDISPATCH for the AcroExch.PDAnnot whose index is obtained. iPDAnnot contains the instance variable m_lpDispatch, which contains the LPDISPATCH.

Returns

The annotation’s index.

GetDoc

Gets the AcroExch.PDDoc associated with the page.

Syntax

LPDISPATCH GetDoc();

Returns

The LPDISPATCH for the page’s AcroExch.PDDoc.

GetNumAnnots

Gets the number of annotations on the page.

Annotations that have associated pop-up windows, such as a strikeout, count as two annotations. Also note that widget annotations (Acrobat form fields) are included.

Syntax

long GetNumAnnots();

Returns

The number of annotations on the page.

GetNumber

Gets the page number of the current page. The first page in a document is page zero.

Syntax

long GetNumber();

Returns

The page number of the current page. The first page in a PDDoc object is page 0.

GetRotate

Gets the rotation value, in degrees, for the current page.

Syntax

short GetRotate();

Returns

Rotation value.

GetSize

Gets a page’s width and height in points.

Syntax

LPDISPATCH GetSize();

Returns

The LPDISPATCH for an AcroExch.Point containing the width and height, measured in points. Point x contains the width, point y the height.

RemoveAnnot

Removes the specified annotation from the page’s annotation array.

Syntax

VARIANT_BOOL RemoveAnnot(long nIndex);

Parameters

Parameter

Description

nIndex

Index within the page’s annotation array of the annotation to be deleted. The first annotation on a page has an index of zero.

Returns

0 if the Acrobat application does not support editing, a positive number otherwise.

SetRotate

Sets the rotation, in degrees, for the current page.

Syntax

VARIANT_BOOL SetRotate(short nRotate);

Parameters

Parameter

Description

nRotate

Rotation value of 0, 90, 180, or 270.

Returns

0 if the Acrobat application does not support editing, -1 otherwise.

AcroExch.PDTextSelect

A selection of text on a single page that may contain more than one disjointed group of words. This is a non-creatable interface. A text selection is specified by one or more ranges of text, with each range containing the word numbers of the selected words. Each range specifies a start and end word, where “start” is the number of the first word of a series of selected words and “end” is the number of the next word after the last word in the selection.

Methods

The PDTextSelect object has the following methods.

Method

Description

Destroy

Destroys a text selection object.

GetBoundingRect

Gets a text selection’s bounding rectangle.

GetNumText

Gets the number of text elements in a text selection.

GetPage

Gets the page number on which the text selection is located.

GetText

Gets the text from the specified element of a text selection.

Destroy

Destroys a text selection object.

Syntax

VARIANT_BOOL Destroy();

Returns

Always returns -1.

GetBoundingRect

Gets a text selection’s bounding rectangle.

Syntax

LPDISPATCH GetBoundingRect();

Returns

The LPDISPATCH for an AcroExch.Rect corresponding to the text selection’s bounding rectangle.

GetNumText

Gets the number of text elements in a text selection. Use this method to determine how many times to call the PDTextSelect. GetText method to obtain all of a text selection’s text.

Note

A text element is not necessarily a word. A text element consists of characters of the same font, size and style; therefore, there may be more than one text element in a word.

Syntax

long GetNumText();

Returns

The number of elements in the text selection.

GetPage

Gets the page number on which the text selection is located.

Syntax

long GetPage();

Returns

The text selection’s page number. The first page in a PDDoc object is page 0.

GetText

Gets the text from the specified element of a text selection. To obtain all the text within the text selection, use PDTextSelect. GetNumText to determine the number of elements in the text selection, then call this method in a loop to obtain each of the elements.

Syntax

BSTR GetText(long nTextIndex);

Parameters

Parameter

Description

nTextIndex

The element of the text selection to get.

Returns

The text, or an empty string if nTextIndex is greater than the number of elements in the text selection.

AcroExch.Point

Defines the location of an AcroPoint.

Properties

The Point object has the following properties.

Property

Description

X

Gets or sets the x-coordinate of an AcroPoint.

Y

Gets or sets the y-coordinate of an AcroPoint.

X

Gets or sets the x-coordinate of an AcroPoint.

Syntax

[get/set] Short

Returns

The x-coordinate of the AcroPoint.

Y

Gets or sets the y-coordinate of an AcroPoint.

Syntax

[get/set] Short

Returns

The y-coordinate of the AcroPoint.

AcroExch.Rect

Defines the location of an AcroRect.

The Rect object has the following properties.

Properties

Property

Description

Bottom

Gets or sets the bottom y-coordinate of an AcroRect.

Left

Gets or sets the left x-coordinate of an AcroRect.

Right

Gets or sets the right x-coordinate of an AcroRect.

Top

Gets or sets the top y-coordinate of an AcroRect.

Bottom

Gets or sets the bottom y-coordinate of an AcroRect.

Syntax

[get/set] Short

Returns

The y-coordinate of the bottom of the AcroRect.

Left

Gets or sets left x-coordinate of an AcroRect.

Syntax

[get/set] Short

Returns

The x-coordinate of the left side of the AcroRect.

Top

Gets or sets the top y-coordinate of an AcroRect.

Syntax

[get/set] Short

Returns

The y-coordinate of the top of the AcroRect.

AcroExch.Time

Defines a specified time, accurate to the millisecond.

Properties

The Time object has the following properties.

Property

Description

Date

Gets or sets the date from an AcroTime.

Hour

Gets or sets the hour from an AcroTime.

Millisecond

Gets or sets the milliseconds from an AcroTime.

Minute

Gets or sets the minutes from an AcroTime.

Month

Gets or sets the month from an AcroTime.

Second

Gets or sets the seconds from an AcroTime.

Year

Gets or sets the year from an AcroTime.

Date

Gets or sets the date from an AcroTime.

Syntax

[get/set] Short

Returns

The date from the AcroTime. The date runs from 1 to 31.

Hour

Gets or sets the hour from an AcroTime.

Syntax

[get/set] Short

Returns

The hour from the AcroTime. The hour runs from 0 to 23.

Millisecond

Gets or sets the milliseconds from an AcroTime.

Syntax

[get/set] Short

Returns

The milliseconds from the AcroTime. Milliseconds run from 0 to 999.

Minute

Gets or sets the minutes from an AcroTime.

Syntax

[get/set] Short

Returns

The minutes from the AcroTime. Minutes run from 0 to 59.

Month

Gets or sets the month from an AcroTime.

Syntax

[get/set] Short

Returns

The month from the AcroTime. The month runs from 1 to 12, where 1 is January and 12 is December.

Second

Gets or sets the seconds from an AcroTime.

Syntax

[get/set] Short

Returns

The seconds from the AcroTime. Seconds run from 0 to 59.

Year

Gets or sets the year from an AcroTime.

Syntax

[get/set] Short

Returns

The year from the AcroTime. The Year runs from 1 to 32767.

AxAcroPDFLib.AxAcroPDF

An object containing a set of methods that provide access to PDF browser controls. This is a creatable interface. This object makes it possible to load a file, move to various pages within the file, and specify various display and print options.

Methods

The AxAcroPDF object has the following methods.

Method

Description

GetVersions

Deprecated

GoBackwardStack

Goes to the previous view on the view stack, if the previous view exists.

GoForwardStack

Goes to the next view on the view stack, if the next view exists.

GotoFirstPage

Goes to the first page in the document, maintaining the current location within the page and zoom level.

GotoLastPage

Goes to the last page in the document, maintaining the current location within the page and zoom level.

GotoNextPage

Goes to the next page in the document, if it exists. Maintains the current location within the page and zoom level.

GotoPreviousPage

Goes to the previous page in the document, if it exists. Maintains the current location within the page and zoom level.

LoadFile

Opens and displays the specified document within the browser.

Print

Prints the document according to the options selected in a user dialog box.

PrintAll

Prints the entire document without displaying a user dialog box.

PrintAllFit

Prints the entire document without displaying a user dialog box, and the pages are shrunk, if necessary, to fit into the imageable area of a page in the printer.

PrintPages

Prints the specified pages without displaying a user dialog box.

PrintPagesFit

Prints the specified pages without displaying a user dialog box.

PrintWithDialog

Prints the document according to the options selected in a user dialog box.

SetCurrentHighlight

Highlights the text selection within the specified bounding rectangle on the current page.

SetCurrentPage

Goes to the specified page in the document.

SetLayoutMode

Sets the layout mode for a page view according to the specified string.

SetNamedDest

Changes the page view to the named destination in the specified string.

SetPageMode

Sets the page mode according to the specified string.

SetShowScrollbars

Determines whether scrollbars will appear in the document view.

SetShowToolbar

Determines whether a toolbar will appear in the viewer.

SetView

Sets the view of a page according to the specified string.

SetViewRect

Sets the view rectangle according to the specified coordinates.

SetViewScroll

Sets the view of a page according to the specified string.

SetZoom

Sets the magnification according to the specified value.

SetZoomScroll

Sets the magnification according to the specified value, and scrolls the page view both horizontally and vertically according to the specified amounts.

Properties

The AxAcroPDF object has the following property.

Property

Description

Src

Gets or sets the URL for the document.

GetVersions

Note

Deprecated. This method is no longer available.

Syntax

VARIANT GetVersions();

GoBackwardStack

Goes to the previous view on the view stack, if the previous view exists. The previous view may be in a different document.

Syntax

void GoBackwardStack();

GoForwardStack

Goes to the next view on the view stack, if the next view exists. The next view may be in a different document.

Syntax

void GoForwardStack();

GotoFirstPage

Goes to the first page in the document, maintaining the current location within the page and the current zoom level.

Syntax

void gotoFirstPage();

GotoLastPage

Goes to the last page in the document, maintaining the current location within the page and the current zoom level.

Syntax

void gotoLastPage();

GotoNextPage

Goes to the next page in the document, if it exists. Maintains the current location within the page and the current zoom level.

Syntax

void gotoNextPage();

GotoPreviousPage

Goes to the previous page in the document, if it exists. Maintains the current location within the page and the current zoom level.

Syntax

void gotoPreviousPage();

LoadFile

Opens and displays the specified document within the browser.

Syntax

VARIANT_BOOL LoadFile(BSTR fileName);

Parameters

Parameter

Description

fileName

The path of the file to be opened.

Returns

0 if the file could not be opened, -1 otherwise.

Print

Prints the document according to the options selected in a user dialog box. The options include embedded printing (printing within a bounding rectangle on a given page), as well as interactive printing to a specified printer. This method returns immediately, even if the printing has not completed.

Note

If security settings do not allow printing, this method is ignored.

Syntax

void Print();

PrintAll

Prints the entire document without displaying a user dialog box. The current printer, page settings, and job settings are used. This method returns immediately, even if the printing has not completed.

Note

If security settings do not allow printing, this method is ignored.

Syntax

void printAll();

PrintAllFit

Prints the entire document without displaying a user dialog box, and the pages are shrunk, if necessary, to fit into the imageable area of a page in the printer. The current printer, page settings, and job settings are used. This method returns immediately, even if the printing has not completed.

Note

If security settings do not allow printing, this method is ignored.

Syntax

void printAllFit(VARIANT_BOOL bOn);

Parameters

Parameter

Description

bOn

Determines whether to scale the imageable area when printing the document. A value of 0 indicates that no scaling should be used, and a positive value indicates that the pages are shrunk, if necessary, to fit into the imageable area of a page in the printer.

PrintPages

Prints the specified pages without displaying a user dialog box. The current printer, page settings, and job settings are used.This method returns immediately, even if the printing has not completed.

Note

If security settings do not allow printing, this method is ignored.

Syntax

void printPages( Long nFrom, Long nTo);

Parameters

Parameter

Description

nFrom

The page number of the first page to be printed. The first page in a document is page 0.

nTo

The page number of the last page to be printed.

PrintPagesFit

Prints the specified pages without displaying a user dialog box. The current printer, page settings, and job settings are used. A parameter specifies whether to shrink pages, if necessary. This method returns immediately, even if the printing has not completed.

Note

If security settings do not allow printing, this method is ignored.

Syntax

void printPagesFit( Long nFrom, Long nTo,
                 VARIANT_BOOL bShrinkToFit);

Parameters

Parameter

Description

nFrom

The page number of the first page to be printed. The first page in a document is page 0.

nTo

The page number of the last page to be printed.

bShrinkToFit

Specifies whether the pages will be shrunk, if necessary, to fit into the imageable area of a page in the printer.

PrintWithDialog

Prints the document according to the options selected in a user dialog box. The options include embedded printing (printing within a bounding rectangle on a given page), as well as interactive printing to a specified printer. This method returns immediately, even if the printing has not completed.

Note

If security settings do not allow printing, this method is ignored.

Syntax

void printWithDialog();

SetCurrentHighlight

Highlights the text selection within the specified bounding rectangle on the current page.

Syntax

void setCurrentHighlight(LONG nLeft, LONG nTop,
                 LONG nRight, LONG nBottom);

Parameters

Parameter

Description

nLeft

The distance in points from the left side of the page.

nTop

The distance in points from the top of the page.

nRight

The width of the bounding rectangle.

nBottom

The height of the bounding rectangle.

SetCurrentPage

Goes to the specified page in the document. Maintains the current location within the page and the current zoom level.

Syntax

void setCurrentPage(LONG nPage);

Parameters

Parameter

Description

nPage

The page number of the destination page. The first page in a document is page 0.

SetLayoutMode

Sets the layout mode for a page view according to the specified string.

Syntax

void setLayoutMode(BSTR szLayoutMode);

Parameters

Parameter

Description

szLayoutMode

Possible values: DontCare: use the current user preference SinglePage: use single page mode (as it would have appeared in pre-Acrobat 3.0 viewers) OneColumn: use one-column continuous mode TwoColumnLeft: use two-column continuous mode with the first page on the left TwoColumnRight: use two-column continuous mode with the first page on the right

SetNamedDest

Changes the page view to the named destination in the specified string.

Syntax

void setNamedDest(BSTR szNamedDest);

Parameters

Parameter

Description

szNamedDest

The named destination to which the viewer will go.

SetPageMode

Sets the page mode according to the specified string.

Syntax

void setPageMode(BSTR szPageMode);

Parameters

Parameter

Description

szPageMode

Possible values: none: displays the document, but does not display bookmarks or thumbnails (default) bookmarks: displays the document and bookmarks thumbs: displays the document and thumbnails

SetShowScrollbars

Determines whether scrollbars will appear in the document view.

Syntax

void setShowScrollbars(VARIANT_BOOL bOn);

Parameters

Parameter

Description

bOn

A positive value indicates that scrollbars will appear, 0 indicates that they will not.

SetShowToolbar

Determines whether a toolbar will appear in the viewer.

Syntax

void setShowToolbar(VARIANT_BOOL bOn);

Parameters

Parameter

Description

bOn

A positive value indicates that the toolbar will appear, 0 indicates that it will not.

SetView

Sets the view of a page according to the specified string.

Syntax

void setView(BSTR szViewMode);

Parameters

Parameter

Description

szViewMode

Possible values: Fit: Fits the entire page within the window both vertically and horizontally. FitH: Fits the entire width of the page within the window. FitV: Fits the entire height of the page within the window. FitB: Fits the bounding box within the window both vertically and horizontally. FitBH: Fits the entire width of the bounding box within the window. FitB: Fits the entire height of the bounding box within the window.

SetViewRect

Sets the view rectangle according to the specified coordinates.

Syntax

void setViewRect(FLOAT left, FLOAT top,
                 FLOAT width, FLOAT height);

Parameters

Parameter

Description

left

The upper left horizontal coordinate.

top

The vertical coordinate in the upper left corner.

width

The horizontal width of the rectangle.

height

The vertical height of the rectangle.

SetViewScroll

Sets the view of a page according to the specified string. Depending on the view mode, the page is either scrolled to the right or scrolled down by the amount specified in offset.

Syntax

void setViewRect(BSTR szViewMode, FLOAT offset);

Parameters

Parameter

Description

szViewMode

Possible values: Fit: Fits the entire page within the window both vertically and horizontally. FitH: Fits the entire width of the page within the window. FitV: Fits the entire height of the page within the window. FitB: Fits the bounding box within the window both vertically and horizontally. FitBH: Fits the entire width of the bounding box within the window. FitBV: Fits the entire height of the bounding box within the window.

offset

The horizontal or vertical coordinate positioned either at the left or top edge.

SetZoom

Sets the magnification according to the specified value.

Syntax

void setZoom(FLOAT percent);

Parameters

Parameter

Description

percent

The desired zoom factor, expressed as a percentage. For example, 1.0 represents a magnification of 100%.

SetZoomScroll

Sets the magnification according to the specified value, and scrolls the page view both horizontally and vertically according to the specified amounts.

Syntax

void setZoomScroll(FLOAT percent, FLOAT left, FLOAT top);

Parameters

Parameter

Description

percent

The desired zoom factor, expressed as a percentage. For example, 1.0 represents a magnification of 100%.

left

The horizontal coordinate positioned at the left edge.

top

The vertical coordinate positioned at the top edge.

Src

Gets or sets the URL for the document.

Syntax

[get/set] src

Returns

The URL for the document, formatted as a string.