Adobe Acrobat Browser Control Type Library 1.0

[Oswalda Shutte]

SinceAcrobat provides the appropriate interfaces to be an OLE server, you can embed PDF documents into documents created by an application that is an OLE client, or link them to OLE containers. However, Acrobat does not perform in-place activation.

The best practical resources for Visual Basic or Visual C# programmers, besides the object browser, are the sample projects. The samples demonstrate use of the Acrobat OLE objects and contain comments describing the parameters for the more complicated methods. For more information, see the Acrobat SDK Samples Guide.

In this approach, you provide a window and a device context, as well as a zoom factor. Acrobat renders the current page into your window. The application must manage the scroll bars and other items in the user interface.

Given the exported interfaces, you can write an application that manipulates various aspects of PDF documents, such as pages, annotations, and bookmarks. Your application might use AVDoc, PDDoc, PDPage, and annotation methods, and might not provide any visual feedback that requires rendering into its application window.

You can launch Acrobat from your own application, which has set up the environment for the user. Your application can cause Acrobat to open a file, set the page location and zoom factor, and possibly even select some text. For example, this could be useful as part of a help system.

You can use the AcroPDF library to display a PDF document in applications using simplified browser controls. In this case, the PDF document is treated as an ActiveX document, and the interface is available in Acrobat Reader.

If possible, use Visual Basic or Visual C#. The run-time type checking offered by the CreateObject call in Visual Basic allows quick prototyping of an application, and in both of these languages the implementation details are simplified.

For comparison, consider the following examples, in which you can see strings with "AcroExch.App" and strings with "Acrobat.CAcroApp". The first is the form for the external string used by OLE clients to create an object of that type. The second is the form that is included in developer type libraries.

In Visual C++, the CAcro classes hide much of the type checking that must be done. Using OLE automation objects in Visual C++ requires an understanding of the AttachDispatch and CreateDispatch methods of the COleDispatchDriver class. For more information, see Using the Acrobat OLE interfaces.

The header files containing the values of constants that are required by C and C++ programmers to use OLE automation are located in the Acrobat SDK IAC directory. Visual Basic and Visual C# users do not need these header files, though it may be useful to refer to them in order to verify the constant definitions.

The only requirement for using the OLE objects made available by Acrobat is to have the product installed on your system and the appropriate type library file included in the project references for your project. The Acrobat type library file is named Acrobat.tlb. This file is included in the InterAppCommunicationSupportHeaders folder in the SDK. Once you have the type library file included in your project, you can use the object browser to browse the OLE objects.

Although you do not need the header files provided in the SDK, you can use them to find the values of various constants, such as AV_DOC_VIEW, that are referenced in the documentation. The file iac.h contains most of these values.

If you were developing in C, these strings would be replaced by a numeric value prior to compilation; passing these strings to the method would not raise an error. When programming in Visual Basic, these strings correspond to constant variables defined in iac.bas.

In some situations, you need to apply a bitwise OR to multiple values and pass the resultant value to a method. For example, in iac.h the ntype parameter of the PDDocSave method is a bitwise OR of the following flags:

For example, if you would like to fully save the PDF file and optimize it for the Web (linearize it) within a Visual Basic application, pass PDSaveFull + PDSaveLinearized (both defined in iac.bas) into the ntype parameter; this is the equivalent of a binary OR of the PDSaveFull and PDSaveLinearized parameters.

In many instances, the numeric values are spelled out in comments in the Visual Basic sample code. However, knowledge of why the methods are structured in this way and how they are used in C can be useful to Visual Basic and Visual C# programmers.

The CAcro classes are defined in the Acrobat type library acrobat.tlb. The OLEView tool in Visual Studio allows you to browse registered type libraries. Use acrobat.tlb when defining OLE automation for a project in Microsoft Visual C++. The files acrobat.h and acrobat.cpp are included in the Acrobat SDK, and implement a type-safe wrapper to the Acrobat automation server.

The COleDispatchDriver class implements the client side of OLE automation, providing most of the code needed to access automation objects. It provides the wrapper functions AttachDispatch, DetachDispatch, and ReleaseDispatch, as well as the convenience functions InvokeHelper, SetProperty, and GetProperty. You employ some of these methods when you use the Acrobat-provided automation objects. Other methods are used in the Acrobat implementation of these objects.

The following is a section of code from acrobat.h that declares t he CAcroHiliteList class. CAcroHiliteList is a subclass of the COleDispatchDriver class, which means that it shares all the instance variables of COleDispatchDriver.

One of these variables is m_lpDispatch, which holds an LPDISPATCH for that object. An LPDISPATCH is a long pointer to an IDispatch, which can be considered an opaque data type representing a dispatch connection. m_lpDispatch can be used in functions that require an LPDISPATCH argument.

Instantiating a class is not sufficient to use it . Before you use an object, you must attach your object to the appropriate Acrobat object by using one of the Dispatch methods of the COleDispatchDriver class. These functions also initialize the m_lpDispatch instance variable for the object.

The GetAVPageView method of the CAcroAVDoc class returns an LPDISPATCH, which is what the AttachDispatch method is expecting for its first argument. The BOOL passed as the second argument indicates whether or not the IDispatch should be released when the object goes out of scope, and is typically TRUE. In general, when an LPDISPATCH is returned from a method such as GetAVPageView, you use AttachDispatch to attach it to an object.

A PDPage object is required because the purpose of this code is to highlight words on the current page. Since it is a CAcro variable, it is necessary to attach to the OLE object before using its methods. CreateDispatch cannot be used to create a PDPage object because "AcroExch.PDPage" is not a valid string for CreateDispatch. However, the AVPageView method GetPage returns an LPDISPATCH pointer for a PDPage object. This is passed as the first argument to the AttachDispatch method of the page object. The TRUE argument indicates that the object is to be released automatically when it goes out of scope.

Calls the CAcroPDPage method CreateWordHilite, which returns an LPDISPATCH for a PDTextSelect. CreateWordHilite takes an LPDISPATCH argument representing a CAcroHilite list. The hilite variable already contains a CAcroHiliteList object, and its instance variable m_lpDispatch contains the LPDISPATCH pointer for the object.

Acrobat provides a rich set of JavaScript programming interfaces that can be used from within the Acrobat environment. It also provides the JSObject interface, which allows external clients to access the same functionality from environments such as Visual Basic.

This procedure adds a reference to the Acrobat type library so that you can access the Acrobat automation APIs, including JSObject, in Visual Basic. Do this before using the JSObject interface, as in the examples that follow.

Select Load from the functions selection box. This creates an empty function stub. The Form1 Load function is called when Form1 is first displayed, so this is a good place to add the initialization code.

You may have a few questions after studying the code. For example, why is jso declared as an Object, while gApp and gPDDoc are declared as types found in the Acrobat type library? Is there a real type for JSObject ?

the compiler compiles the code, but fails at run time. Visual Basic has no type information for JSObject, so Visual Basic does not know if a particular call is syntactically valid until run-time, and will compile any function call to a JSObject. For that reason, you must rely on the documentation to know what functionality is available through the JSObject interface. For details, see the JavaScript for Acrobat API Reference.

You may also wonder why it is necessary to open a PDDoc before creating a JSObject. Running the program shows that no document appears onscreen, and suggests that using the JavaScript console should be possible without a PDDoc. However, JSObject is designed to work closely with a particular document, as most of the available features operate at the document level. There are some application-level features in JavaScript (and therefore in JSObject), but they are of secondary interest. In practice, a JSObject is always associated with a particular document.

Some standard Acrobat automation methods are used to determine the size of the first page in the document. These numbers are critical to achieving the correct layout, because the PDF coordinate system is based in the lower-left corner of the page, but the annotation will be anchored at the upper left corner of the page.

First, addAnnot looks as if it is a method of JSObject, but the JavaScript reference shows that the method is associated with the doc object. You might expect the syntax to be jso.doc.addAnnot. However, jso is the Doc object, so jso.addAnnot is correct. All of the properties and methods in the Doc object are used in this manner.

3a8082e126