Working with PdfUnderlay Entities

What is a PDF underlay?

A PDF (Portable Document Format) underlay is an entity that represents a .pdf file attached to a drawing database and referenced from that database. A PDF underlay entity references an external PDF document, which is not an essential part of a drawing database but can be processed (for example, rendered) by Drawings SDK. The following picture illustrates a few renderings of a PDF underlay entity:

The original .pdf file (left) and a drawing with disabled PDF layers (right):
A .pdf file rendered in monochrome mode (left) and a .pdf file with applied clipping (right):

PDF Underlay Support in Drawings SDK

Drawings SDK provides PDF underlay support with the Google PDFium library. To get detailed information about working with PDF underlays using Google PDFium, see PDF Underlays with Google PDFium.

Drawings SDK provides a unified public API for PDF underlay functionality based on the Google PDFium library.

All source is available in the release packages (in the Drawing/Extensions/PdfUnderlayCommon folder). For the API Reference, please refer to:

PdfUnderlayModule class
OdDbPdfDefinition class
OdDbPdfReference class

Adding a PDF Underlay Entity to a Drawing

Let's assume that you want to add the following .pdf file to model space as an underlaying entity.

To add a .pdf file to model space as an underlaying entity:

Define a custom services class inherited from the ExSystemServices and ExHostAppServices classes to provide access to platform-dependent functionality:


class MyServices : public ExSystemServices, public ExHostAppServices
{
protected:
  ODRX_USING_HEAP_OPERATORS(ExSystemServices);
};

Create an instance of the custom services class and initialize Drawings functionality:
```
OdStaticRxObject svcs;
odInitialize(&svcs);
        
```

Download the contents of a .dwg file to a newly created drawing database:


OdString fileName = svcs.findFile(L"Template_ISO_1.dwg");
OdDbDatabasePtr pDb = svcs.readFile(fileName);

Open model space of the database for writing:


OdDbBlockTableRecordPtr bBTR = pDb->getModelSpaceId().safeOpenObject(OdDb::kForWrite);

Load the module for working with PDF underlays and check whether the load was successful:


if (OdDbPdfDefinition::loadPdfUnderlayModule().isNull())
  throw OdError(eNullObjectPointer);

Get a smart pointer to the instance of the underlay host protocol extension (an OdDbUnderlayHostPE object), and check the result:


OdDbUnderlayHostPEPtr pHost = OdDbPdfDefinition::desc()->getX(OdDbUnderlayHostPE::desc());

if (!pHost.get())
  throw OdError(eNullObjectPointer);

Load the content of the .pdf file for the underlay (it is assumed below that the underlayFilePath variable is an OdString object that contains the full path to the .pdf file):
```
OdDbUnderlayFilePtr pUnderlayFile;

OdResult res = pHost->load(*pDb, underlayFilePath, "", pUnderlayFile);

if (res != eOk)
  throw OdError(res);
        
```
Create a PDF object definition (through an instance of the OdDbPdfDefinitionclass), and set the source .pdf file and the page number that contains the underlay data:
```
OdDbUnderlayDefinitionPtr pPdfDef = OdDbPdfDefinition::createObject();
OdString itemName(OD_T("1"));
pPdfDef->setSourceFileName(underlayFilePath);
pPdfDef->setItemName(itemName);
        
```
Note that the setItemName() method sets the number of the PDF document's page. Pages are enumerated starting from 1.
Add the created definition object to the drawing database:
```
OdDbObjectId idDef = pPdfDef->postDefinitionToDb(pDb, OD_T("DocSnippets_Cmds_") + itemName);
        
```
The PDF definition object is then in the database structure:

Create a PDF reference object and append it to model space:


OdDbUnderlayReferencePtr pPdfRef = OdDbPdfReference::createObject();
pPdfRef->setDatabaseDefaults(pDb);

bBTR->appendOdDbEntity(pPdfRef);

Associate the previously created PDF underlay definition object with the PDF reference object:
```
pPdfRef->setDefinitionId(idDef);
        
```
The PDF reference object is added to model space and references the PDF definition object:

A rendering of the PDF underlay looks like the following:

Before finishing your client application, do not forget to deinitialize Drawings SDK functionality:


odUninitialize();

The loadPdfUnderlayModule() method of the OdDbPdfDefinition class tries to load the PDFiumModule first and if it fails, tries to load the PdfModuleVI module; therefore to force using the PdfModuleVI, you need to load it explicitly:


if (::odrxDynamicLinker()->loadModule(OdPdfModuleVIModuleName).isNull())
  throw OdError(eNullObjectPointer);

Instead of:


if (OdDbPdfDefinition::loadPdfUnderlayModule().isNull())
  throw OdError(eNullObjectPointer);

Sample Applications

Additional examples for working with PDF underlay entities are located in the sample applications:

OdWriteEx sample application illustrates adding a PdfUnderlay entity to a drawing database.
Location: Drawing/Examples/OdWriteEx.
See the addPdfUnderlay() method of the DbFiller class declared in the DbFiller.h file and its implementation in the appropriate DbFiller.cpp file.
OdaMfcApp sample application provides functionality for adding PDF underlay entities to a drawing database that is accessible by choosing Insert -> Pdf Underlay:

The Insert PDF underlay dialog window displays:

You can switch on or off any of the available layers from the origin PDF document in the layers list:

To select a .pdf file for the underlay, click Browse. To insert the underlaying entity, click Insert.

In addition, there are two user commands related to PDF underlay support that are available from the main menu:
- showPdfGrips
- showPdfSnaps
Location: Core\Examples\win\OdaMfcApp.

Note that the OdaMfcApp sample is available only for Windows platforms.
ExCustObjs sample application contains the implementation for the showPdfGrips and showPdfSnaps commands. See the function _showPdfGrips_func() for the showPdfGrips command implementation and the function _showPdfSnaps_func() for the showPdfSnaps command implementation. Both functions are defined in the DrxDebugCmds.cpp source file.
Location: Drawing/Examples/ExCustObjs.

What is a PDF underlay?

PDF Underlay Support in Drawings SDK

Adding a PDF Underlay Entity to a Drawing

Sample Applications

See Also