Breadcrumbs

Handling View and Print Visibility of Optional Content Groups (Layers)

📌 Overview

This article explains how to control the visibility of Optional Content Groups (OCGs, also known as layers) for viewing and printing in a PDF using the Mako SDK.

While layers can be toggled globally, PDF specifications allow for specific “Usage” states that define whether a layer should be visible when the document is viewed on screen versus when it is sent to a printer. This is particularly useful for technical drawings, watermarks, or internal notes that should not appear in the final print output.

📗 Instructions

To set the view and print visibility of a layer:

  1. Create/Access the Optional Content Group (OCG): Retrieve the specific IOptionalContentGroup you wish to modify.

  2. Get or Create Usage Information: Use getUsage() on the OCG. If it doesn't exist, you may need to create it.

  3. Set usage applications for the default configuration: Use optionalContent->getDefaultConfiguration() andconfig->setAutoStates().

  4. Configure Rendering (Optional): When rendering the PDF within Mako (e.g., using IJawsRenderer), ensure the optionalContentUsage parameter is set to respect these states (e.g., eOCEView or eOCEPrint).

⌨️ Sample Code

The following C++ example demonstrates how to create a PDF where different layers are specifically flagged for viewing or printing. Full code can be found at OptionalContentVisibility.cpp.

C++
// Create 3 optional content groups and associate the text with the appropriate optional content groups 
auto optionalContent = IOptionalContent::create(mako);
document->setOptionalContent(optionalContent);

auto groupBoth = optionalContent->makeNewGroup("Both", true);
auto groupView = optionalContent->makeNewGroup("View only", true);
auto groupPrint = optionalContent->makeNewGroup("Print only", true);

optionalContent->makeNodeOptional(glyphBoth, groupBoth);
optionalContent->makeNodeOptional(glyphView, groupView);
optionalContent->makeNodeOptional(glyphPrint, groupPrint);

// Set the usage for each group to specify when the content in each group should be visible. 
auto makeUsage = [&](const IOptionalContentGroupPtr& group,
    eOptionalContentVisibility view,
    eOptionalContentVisibility print)
    {
        auto usage = IOptionalContentGroupUsage::create(mako);
        usage->setViewVisibility(view);
        usage->setPrintVisibility(print);
        group->setUsage(usage);
    };

makeUsage(groupBoth, eOCVVisible, eOCVVisible);
makeUsage(groupView, eOCVVisible, eOCVInvisible);
makeUsage(groupPrint, eOCVInvisible, eOCVVisible);

// --- Set usage applications for the default configuration ---
auto config = optionalContent->getDefaultConfiguration();
config->setBaseState(eOCVVisible);

COptionalContentGroupReferenceVect allGroups;
allGroups.append(groupBoth->getReference());
allGroups.append(groupView->getReference());
allGroups.append(groupPrint->getReference());

auto makeUsageApplication = [&](
    eOptionalContentEvent event,
    eOptionalContentCategory category)
    {
        auto app = IOptionalContentGroupUsageApplication::create(mako, event);
        COCCategoryVect categories;
        categories.append(category);
        app->setCategories(categories);
        app->setAffectedOptionalContentGroups(allGroups);
        return app;
    };

COptionalContentGroupUsageApplicationVect apps;
apps.append(makeUsageApplication(eOCEView, eOCCView));
apps.append(makeUsageApplication(eOCEPrint, eOCCPrint));
config->setAutoStates(apps);

🎨 Results

When the resulting PDF is opened in a viewer like Adobe Acrobat:

  • Layers set with View only will be hidden in the print preview and final printout.

  • Layers set with Print only will be hidden during normal on-screen viewing.

  • These attributes can be verified in the “Layer Properties” dialog in Acrobat.

☑️ Conclusion

By utilizing the IOptionalContentGroupUsage interface, developers can fine-tune how PDF content behaves in different contexts. This ensures that the digital representation and the physical printout contain exactly the information intended for each medium.

📚 Additional Resources