Writing Snippets

A code snippet must contain at least the following:

  • A single main function that acts as its entry point. Snippets may contain additional functions as needed.

  • A macro call that binds the snippet to the SnippetRunner environment.

An example of a single-function snippet that is included with the SnippetRunner project, SimpleSnip.cpp, is shown below. The code for this snippet also includes comments (not shown here) that provide useful development hints.

#include "SnippetRunner.h"
 #include "SnippetRunnerUtils.h"

 void SimpleSnip()
 {
     Console::displayString("This is a simple snippet.");
     Console::displayString("Simple snippet executed");
 }

 SNIPRUN_REGISTER(SimpleSnip, "Simple Framework", "SimpleSnip creates a framework for a snippet.")

This snippet has a single function, SimpleSnip, which writes two messages to the output pane of the Common Interface (see Using the Common Interface) using the utility function Console::displayString. This function enables you to perform memory dumps and view strings (char * ), ASText objects, and Cos objects. (See the source files SnippetRunnerUtils.cpp and Console.cpp for details.)

Because the SimpleSnip function requires no parameters, it uses the macro call SNIPRUN_REGISTER to bind to the SnippetRunner environment. (See Passing parameters to snippets for other possibilities.) This macro requires three parameters:

  • The name of the function that is the entry point for the snippet (the same as the snippet’s file name).

  • A string indicating where the snippet’s node is to appear in the Snippet Collection pane of the Common Interface user interface. If the snippet location is not at the root level of the hierarchy, the string specifies the path to the snippet, with folder names separated by colons. For example, the GetFontInfoSnip snippet would specify: “PD Layer:Fonts:Get Font Info”.

  • A string of descriptive text to be presented in the Snippet Description pane.

Tip

A snippet’s node name is limited to 49 characters.

SimpleSnip is a synchronous or “one-shot” snippet, meaning that it executes and then terminates. See Toggling behavior and asynchronous snippets for other possibilities.

Passing parameters to snippets

You can pass parameters to a snippet’s main function. To enable this mechanism, use the SNIPRUN_REGISTER_WITH_DIALOG macro in your snippet to bind the snippet to SnippetRunner. This call takes an extra parameter (beyond the three required by SNIPRUN_REGISTER ), which is a single string representing default parameter(s) separated by spaces.

When a snippet implemented with SNIPRUN_REGISTER_WITH_DIALOG is invoked, a dialog box with the snippet’s descriptive text appears that includes a text edit box pre-populated with the default values set by the fourth parameter.

If necessary, this dialog box can be suppressed using the utility calls turnParamDialogOff (/On ) and toggleParamDialog (see SnippetRunnerUtils.cpp).

An example of the use of this macro and its resulting values is in the TextChangeColour snippet, whose macro call is written as follows:

SNIPRUN_REGISTER_WITH_DIALOG(TextChangeColourSnip, "PDE Layer:
      Text:Change colour","Shows how to change the colour of text
      in a document","0 0 65000")

When this snippet is invoked, a dialog box displays “Shows how to change colour of text in a document” and the parameter text edit box is pre-populated with the default values: “0 0 65000”. For this example, the parameters are meant to represent RGB color values. You can edit the text in the dialog box to change the values of the parameters.

To access the parameters passed in through the dialog box, use the ParamsManager class. This class (see ParamManager.cpp) provides a set of methods that allow you to obtain the input parameters as integer, string, hex, and fixed data types. (To provide support for other data types, you must extend the ParamsManager class.)

For example, the TextChangeColour function is defined with a single parameter of type ParamManager * , to provide storage for the snippet’s parameters:

void TextChangeColourSnip(ParamManager * thePM)

The following code in the TextChangeColourSnip function converts the input parameter string to three separate RGB values of type integer:

ASInt32 red,green,blue;

 thePM->getNextParamAsInt(red);
 thePM->getNextParamAsInt(green);
 thePM->getNextParamAsInt(blue);

Toggling behavior and asynchronous snippets

This section applies to Acrobat plug-in snippets only; not to the PDF Library SDK.

SnippetRunner provides utility methods for toggling behavior. For example, FormCalculationsSnip turns on and off the ability to perform form calculations. It uses the toggleSnippetCheck method (see SnippetRunnerUtils.cpp) to turn the state on if it was previously off, and vice versa.

Other snippets that toggle behavior include AVPageViewToggleWireframeDrawingSnip, and AVAppShowAnnotProperties.

Some snippets define and register callbacks in the same manner as plug-ins. (See the Acrobat and PDF Library API Reference and Plugin Developer Guide for information regarding ASCallback objects, ASCallbackCreateProto and ASCallbackDestroy ). Specifically, to register a snippet for a notification, use AVAppRegisterNotification and provide a callback function with the appropriate arguments. To register your snippet for a specific event, such as IdleProc , PageViewDrawing , PageViewClicks or PageViewAdjustCursor , use the related AVAppRegister XXX method. You can toggle a snippet to Off by checking for its On state and unregistering via the complementary AVAppUnregister XXX method.

Such snippets can be asynchronous in the sense that they register a callback whose output (or other result) does not appear until a particular event occurs. Snippets that register for notifications include: OptContNotificationTracerSnip , AVAppFrontDocChangeNotSnip , AVAppRegisterForPageViewDrawingSnip , PDDocDidDeletePagesNotSnip and IdleProcSnip.

Handling exceptions

The SnippetRunner provides an exception handler that reports the name of the snippet that caused an exception. Synchronous snippets require no special considerations with regard to exception handling within the SnippetRunner environment.

However, if you write a snippet containing a callback that is called asynchronously, the callback function should include its own exception handlers to trap and handle various exceptions. When an exception occurs, your exception handler can perform any necessary cleanup, such as releasing memory. The core API provides the following macros for handling errors: DURING , HANDLER , END_HANDLER and E_RETURN. If methods in your snippet code could return an error code or NULL if something goes wrong, you can call the ASRaise method, which generates an exception.

Handling documents

SnippetRunner provides a C++ class, CDocument , that handles getting documents in the SnippetRunner environment. (See CDocument.h and CDocument.cpp.)

To use this class, a document must be open. You declare a CDocument object and then cast it to the type you need. For example:

CDocument document;
 AVDocGetFoo((AVDoc)document);

Supported cast types are:

  • AVDoc — The front document (does not apply to PDF Library)

  • PDDoc — The front AVDoc in Acrobat or the document that is open in PDF Library

  • CosDoc — Derived from the current PDDoc

  • AVPageView — The current page view in the front document (does not apply to PDF Library)

  • PDPage — The page associated with the current page view in Acrobat (or the page that has been set in PDF Library). It defaults to the first page.

The destructor method of CDocument is called when the snippet returns. Therefore, you do not need to write code to release or destroy these objects.