Click here to close now.

Welcome!

You will be redirected in 30 seconds or close now.

ColdFusion Authors: Yakov Fain, Maureen O'Gara, Nancy Y. Nee, Tad Anderson, Daniel Kaar

Related Topics: Adobe Flex, ColdFusion

Adobe Flex: Tutorial

Creating Layered PDFs with Escape Calls to the PDF Converter Printer

PDF Layers are called Optional Content within the PDF specifications

Background information
PDF Layers are called Optional Content within the PDF specifications. This is a feature that was added as of PDF-1.5 (Acrobat 6.) A layer is identified by an identifier and a title. Only the layer title is visible to the end-user of the PDF document. Layers can be structured as a tree or as a hierarchy of layers.  Here is a sample Optional Content object in a PDF:

9 0 obj <</Type/OCG/Name(Blue Layer) >> endobj

Each page using this layer should add the layer to its list of resources, for example:

6 0 obj <</Type /Page /Parent 3 0 R /MediaBox [0 0 612 792 ] /Contents [7 0 R ]
/Resources << /ProcSet [/PDF /Text] /Font <</F10 10 0 R >>
/Properties <</OC9 9 0 R >>
>> >> endobj


OC9 is the layer ID (Blue Layer) and is the layer title (strings in PDF are surrounded by parenthesis). To indicate that various objects within the page content belong to specific layers, the following syntax is used:

% start the Blue Layer that contains the text: Page 1
/OC /OC9 BDC
BT /F10 5.76  Tf 1 0 0 1 24 745.56 Tm 0.026  Tc -0.067  Tw (Page 1) Tj ET

% start a sub-layer that will contain a filled rectangle
/OC /OC11 BDC
n 1 g 96 326.96 35.76 -6.6 re f*
% end of sub-layer 1
EMC

% start another sub-layer that will contain another filled rectangle
/OC /OC13 BDC
n 1 g 96 526.96 35.76 -6.6 re f*
% end of sub-layer 2
EMC


%end of blue layer
EMC


Although the code shows one parent layer and two nested layers (contained within the parent layer), this is not enough to define the hierarchy of layers. The Order string is used to determine the hierarchy of layers. The Order string is part of the document Catalog. The Order string for the above PDF sample should look like this:

/Order [ 9 0 R [11 0 R 13 0 R] ]

The object IDs are needed to create a proper order string. The order string can also contain a parent node that is not a layer but only a container for other layers. In the example above we could have all the layers below to one parent layer called (Layered PDF) by using:

/Order [ (Layered PDF)  9 0 R [11 0 R 13 0 R]  ]

It is important that the Order string matches the order of layers as they appear in the page content, otherwise the PDF viewer will not be able to properly “show and hide” layers with their sub-layers.

Note: There is an inconsistency in the PDF specifications related to defining nodes that are parents of other layers. To have a Layered PDF as the parent of layer 9, we do not use [(Layered PDF) [9 0 R] ] as one might expect but [(Layered PDF) 9 0 R] as if the 2 nodes were on the same level.

Creating Groups of Layers
The PDF format allows creating groups of mutually exclusive layers where showing one layer will automatically hide the other. These are called radio-button groups and defined using the RBGroups PDF keyword. One can also define which layers are visible by default and which are hidden, for example:

/RBGroups [[ 11 0 R 13 0 R]]  /ON[ 11 0 R] /OFF [13 0 R] indicates that layers 11 and 13 are grouped and that layer 11 is visible by default whereas 13 is invisible.

Dynamically Creating Layers using the Amyuni PDF Converter
External developers need to be aware of layer titles only. The layers IDs and object numbers are not significant to the developer, so the implemented API will only use layer titles to insert layers and define the layer hierarchy.

Layers can be inserted within a PDF file while the document is being printed by calling Escape sequences. Escape sequences are GDI artifacts that enable developers to send custom data to a printer driver.

Checking that the Printer supports PDF Layers
The first step to start adding layers is to check that the printer has support for the escape sequences that are defined by Amyuni. The following calls are needed include:

// check if PDF printer supports layers
#define ESCAPE_SETLAYER        248

CHAR    technology[4];
int escape = ESCAPE_SETLAYER;
ExtEscape( hDC, GETTECHNOLOGY, 0, NULL, sizeof(technology), (LPSTR)technology
);

// the technology should be PDF
if ( lstrcmp(technology, "PDF") )
{
MessageBox( 0, "Not an Amyuni PDF driver", "Error", MB_ICONERROR );
}

// and support the SETLAYER escape
if ( !ExtEscape( hDC, QUERYESCSUPPORT, sizeof(escape), (LPCSTR)&escape, 0,
NULL ) )   
{
MessageBox( 0, "Not an Amyuni PDF driver", "Error", MB_ICONERROR );
}

GETTECHNOLOGY and QUERYESCSUPPORT are escape sequences that are predefined by Windows GDI. ESCAPE_SETLAYER is a custom escape that is processed by the Amyuni printer.

The SETLAYER escape takes one parameter which is a Unicode string, The escape can be wrapped into a helper function such as:

void SetLayer( HDC hDC, LPWSTR LayerInfo )
{
switch ( ExtEscape( hDC, ESCAPE_SETLAYER, (int)((wcslen(LayerInfo) + 1)
* sizeof(LayerInfo[0])), (LPCSTR)LayerInfo, 0, NULL ) )
{
default:
// positive return indicates success
case 0:
// no error
return;

case -1:
// error occured, closing a layer when none was open
break;

case -2:
// memory allocation error (low memory or invalid string)
break;
}
}

The same escape call is used to start a layer or sub-layer, end a layer or define the hierarchy of layers.

Setting the Hierarchy of Layers
The order or hierarchy of layers is sent to the PDF printer using the SETLAYER escape before the call to StartDoc. It can actually be called anytime during the printing as long as the call is made outside of a StartPage/EndPage block but before the EndDoc is called. The advantage of setting the hierarchy before StartDoc is that it allows the PDF printer to expect layer support and switch the file header to PDF-1.5.

If the hierarchy of layers is not known before the call the StartDoc, the developer can call SetLayer( L"" ) with an empty string before the call to StartDoc simply to instruct the PDF printer to output PDF-1.5 header. The order string should contain the titles of all the layers and their hierarchy, all in Unicode format. E.g.:

// set the order and hierrachy of layers
SetLayer( hDC, L"/Order[(Blue Layer)[(Blue Layer - 1)(Blue Layer - 2)](Red
Layer)(Green Layer)]"
);

This will produce a layer structure like this:



To group layers within radio-button groups, the /RBGroups, /ON and /OFF entries should be added to the call above. This code for e.g. will make the red and green layers as part of a group:

// set the order and radio/button groups of layers
SetLayer( hDC, L"/Order[(Blue Layer)[(Blue Layer - 1)(Blue Layer - 2)](Red
Layer)(Green Layer)]" \
L"/RBGroups[[(Red Layer)(Green Layer)]]/OFF[(Red Layer)]/ON[(Green Layer)]"

);

Drawing Objects within Layers
Within a StartPage/EndPage sequence of calls, calling SetLayer with a valid layer title will start a new layer and place all subsequent drawing instructions within that layer. Calling SetLayer with an empty string will end the last layer. If multiple layers are nested, multiple calls to SetLayer with an empty string are needed to close all layers.

If all layers are not closed at the call to EndPage, the PDF printer will automatically close all open layers, for example:


// start parent layer
SetLayer( hDC, L"Blue Layer" );
SetTextColor( hDC, RGB(0, 0, 255) );
TextOut( hDC, 200, yPos, buf, lstrlen(buf) );
yPos += 200;

// start blue sub-layer 1
SetLayer( hDC, L"Blue Layer - 1" );
SetTextColor( hDC, RGB(0, 0, 128) );
TextOut( hDC, 800, yPos, "Blue Layer - 1", lstrlen("Blue Layer - 1") );
yPos += 200;
SetLayer( hDC, L"" );    // close blue sub-layer 1
SetLayer( hDC, L"" );    // close blue parent layer

The sequence of opening and closing layers should be consistent with the order string for the PDF viewer to show or hide layers with their sub-layers in a consistent way.

The contents for this post were provided by Dany Amiouny using the Amyuni PDF Converter developer tool.

Please visit us at www.amyuni.com to learn more about Amyuni Developer Pro tools or our Professional Services page to contact one of our qualified PDF experts.

More Stories By Amyuni Tech

Franc Gagnon is a technical copywriter for Amyuni Technologies–a PDF solution provider. Amyuni products are integrated into applications used worldwide. The company's software tools are the PDF engines behind several leading business applications created by large software companies such as Intuit, Sage, CaseWare and many more.

@ThingsExpo Stories
Wearable technology was dominant at this year’s International Consumer Electronics Show (CES) , and MWC was no exception to this trend. New versions of favorites, such as the Samsung Gear (three new products were released: the Gear 2, the Gear 2 Neo and the Gear Fit), shared the limelight with new wearables like Pebble Time Steel (the new premium version of the company’s previously released smartwatch) and the LG Watch Urbane. The most dramatic difference at MWC was an emphasis on presenting wearables as fashion accessories and moving away from the original clunky technology associated with t...
SYS-CON Events announced today that robomq.io will exhibit at SYS-CON's @ThingsExpo, which will take place on June 9-11, 2015, at the Javits Center in New York City, NY. robomq.io is an interoperable and composable platform that connects any device to any application. It helps systems integrators and the solution providers build new and innovative products and service for industries requiring monitoring or intelligence from devices and sensors.
Internet of Things (IoT) will be a hybrid ecosystem of diverse devices and sensors collaborating with operational and enterprise systems to create the next big application. In their session at @ThingsExpo, Bramh Gupta, founder and CEO of robomq.io, and Fred Yatzeck, principal architect leading product development at robomq.io, will discuss how choosing the right middleware and integration strategy from the get-go will enable IoT solution developers to adapt and grow with the industry, while at the same time reduce Time to Market (TTM) by using plug and play capabilities offered by a robust I...
After making a doctor’s appointment via your mobile device, you receive a calendar invite. The day of your appointment, you get a reminder with the doctor’s location and contact information. As you enter the doctor’s exam room, the medical team is equipped with the latest tablet containing your medical history – he or she makes real time updates to your medical file. At the end of your visit, you receive an electronic prescription to your preferred pharmacy and can schedule your next appointment.
SYS-CON Events announced today that Solgenia will exhibit at SYS-CON's 16th International Cloud Expo®, which will take place on June 9-11, 2015, at the Javits Center in New York City, NY, and the 17th International Cloud Expo®, which will take place on November 3–5, 2015, at the Santa Clara Convention Center in Santa Clara, CA. Solgenia is the global market leader in Cloud Collaboration and Cloud Infrastructure software solutions. Designed to “Bridge the Gap” between Personal and Professional Social, Mobile and Cloud user experiences, our solutions help large and medium-sized organizations dr...
While not quite mainstream yet, WebRTC is starting to gain ground with Carriers, Enterprises and Independent Software Vendors (ISV’s) alike. WebRTC makes it easy for developers to add audio and video communications into their applications by using Web browsers as their platform. But like any market, every customer engagement has unique requirements, as well as constraints. And of course, one size does not fit all. In her session at WebRTC Summit, Dr. Natasha Tamaskar, Vice President, Head of Cloud and Mobile Strategy at GENBAND, will explore what is needed to take a real time communications ...
The world's leading Cloud event, Cloud Expo has launched Microservices Journal on the SYS-CON.com portal, featuring over 19,000 original articles, news stories, features, and blog entries. DevOps Journal is focused on this critical enterprise IT topic in the world of cloud computing. Microservices Journal offers top articles, news stories, and blog posts from the world's well-known experts and guarantees better exposure for its authors than any other publication. Follow new article posts on Twitter at @MicroservicesE
SYS-CON Events announced today that Litmus Automation will exhibit at SYS-CON's 16th International Cloud Expo®, which will take place on June 9-11, 2015, at the Javits Center in New York City, NY. Litmus Automation’s vision is to provide a solution for companies that are in a rush to embrace the disruptive Internet of Things technology and leverage it for real business challenges. Litmus Automation simplifies the complexity of connected devices applications with Loop, a secure and scalable cloud platform.
SYS-CON Events announced today the IoT Bootcamp – Jumpstart Your IoT Strategy, being held June 9–10, 2015, in conjunction with 16th Cloud Expo and Internet of @ThingsExpo at the Javits Center in New York City. This is your chance to jumpstart your IoT strategy. Combined with real-world scenarios and use cases, the IoT Bootcamp is not just based on presentations but includes hands-on demos and walkthroughs. We will introduce you to a variety of Do-It-Yourself IoT platforms including Arduino, Raspberry Pi, BeagleBone, Spark and Intel Edison. You will also get an overview of cloud technologies s...
Containers and microservices have become topics of intense interest throughout the cloud developer and enterprise IT communities. Accordingly, attendees at the upcoming 16th Cloud Expo at the Javits Center in New York June 9-11 will find fresh new content in a new track called PaaS | Containers & Microservices Containers are not being considered for the first time by the cloud community, but a current era of re-consideration has pushed them to the top of the cloud agenda. With the launch of Docker's initial release in March of 2013, interest was revved up several notches. Then late last...
The WebRTC Summit 2015 New York, to be held June 9-11, 2015, at the Javits Center in New York, NY, announces that its Call for Papers is open. Topics include all aspects of improving IT delivery by eliminating waste through automated business models leveraging cloud technologies. WebRTC Summit is co-located with 16th International Cloud Expo, @ThingsExpo, Big Data Expo, and DevOps Summit.
SOA Software has changed its name to Akana. With roots in Web Services and SOA Governance, Akana has established itself as a leader in API Management and is expanding into cloud integration as an alternative to the traditional heavyweight enterprise service bus (ESB). The company recently announced that it achieved more than 90% year-over-year growth. As Akana, the company now addresses the evolution and diversification of SOA, unifying security, management, and DevOps across SOA, APIs, microservices, and more.
The list of ‘new paradigm’ technologies that now surrounds us appears to be at an all time high. From cloud computing and Big Data analytics to Bring Your Own Device (BYOD) and the Internet of Things (IoT), today we have to deal with what the industry likes to call ‘paradigm shifts’ at every level of IT. This is disruption; of course, we understand that – change is almost always disruptive.
SYS-CON Events announced today that SafeLogic has been named “Bag Sponsor” of SYS-CON's 16th International Cloud Expo® New York, which will take place June 9-11, 2015, at the Javits Center in New York City, NY. SafeLogic provides security products for applications in mobile and server/appliance environments. SafeLogic’s flagship product CryptoComply is a FIPS 140-2 validated cryptographic engine designed to secure data on servers, workstations, appliances, mobile devices, and in the Cloud.
GENBAND has announced that SageNet is leveraging the Nuvia platform to deliver Unified Communications as a Service (UCaaS) to its large base of retail and enterprise customers. Nuvia’s cloud-based solution provides SageNet’s customers with a full suite of business communications and collaboration tools. Two large national SageNet retail customers have recently signed up to deploy the Nuvia platform and the company will continue to sell the service to new and existing customers. Nuvia’s capabilities include HD voice, video, multimedia messaging, mobility, conferencing, Web collaboration, deskt...
SYS-CON Media announced today that @WebRTCSummit Blog, the largest WebRTC resource in the world, has been launched. @WebRTCSummit Blog offers top articles, news stories, and blog posts from the world's well-known experts and guarantees better exposure for its authors than any other publication. @WebRTCSummit Blog can be bookmarked ▸ Here @WebRTCSummit conference site can be bookmarked ▸ Here
SYS-CON Events announced today that Cisco, the worldwide leader in IT that transforms how people connect, communicate and collaborate, has been named “Gold Sponsor” of SYS-CON's 16th International Cloud Expo®, which will take place on June 9-11, 2015, at the Javits Center in New York City, NY. Cisco makes amazing things happen by connecting the unconnected. Cisco has shaped the future of the Internet by becoming the worldwide leader in transforming how people connect, communicate and collaborate. Cisco and our partners are building the platform for the Internet of Everything by connecting the...
Temasys has announced senior management additions to its team. Joining are David Holloway as Vice President of Commercial and Nadine Yap as Vice President of Product. Over the past 12 months Temasys has doubled in size as it adds new customers and expands the development of its Skylink platform. Skylink leads the charge to move WebRTC, traditionally seen as a desktop, browser based technology, to become a ubiquitous web communications technology on web and mobile, as well as Internet of Things compatible devices.
Docker is an excellent platform for organizations interested in running microservices. It offers portability and consistency between development and production environments, quick provisioning times, and a simple way to isolate services. In his session at DevOps Summit at 16th Cloud Expo, Shannon Williams, co-founder of Rancher Labs, will walk through these and other benefits of using Docker to run microservices, and provide an overview of RancherOS, a minimalist distribution of Linux designed expressly to run Docker. He will also discuss Rancher, an orchestration and service discovery platf...
SYS-CON Events announced today that Vitria Technology, Inc. will exhibit at SYS-CON’s @ThingsExpo, which will take place on June 9-11, 2015, at the Javits Center in New York City, NY. Vitria will showcase the company’s new IoT Analytics Platform through live demonstrations at booth #330. Vitria’s IoT Analytics Platform, fully integrated and powered by an operational intelligence engine, enables customers to rapidly build and operationalize advanced analytics to deliver timely business outcomes for use cases across the industrial, enterprise, and consumer segments.