Working with PDF annotations using C#: Widget Annotation

Since PDF v 1.2 we can use widgets. They are interactive form elements that we can add to a PDF to make it easier to enter, submit information, or perform some other user interactions. Despite the fact that widgets are a special type of annotations, we can’t create theirs as annotation directly, because the Widget Annotation is the form field’s graphical representation on the specific pages.

Each form field for each place in the document represents one Widget Annotation. The location-specific data of Widget Annotation are added to the particular page. Each form field has several variations. A button can be a radio button, a checkbox, or a push-button. A choice widget can be a list box or a combo box.

In this sample, we will learn how to add the push-buttons for navigation in the document. As in the previous posts, I use an Aspose.PDF for .NET library.

Adding buttons to the document

To add a button to the page we need only 5 lines of code:

var document = new Document(<filename>);
var page = document.Pages[1];
var rect = new Rectangle(72, 748, 144, 768);
var button = new ButtonField(page, rect);
document.Form.Add(button);

Our button will be displayed only on the page and will have a standard design and do nothing. Let’s customize it: make this button colored and add other properties for more informative use.

document = new Document();
var page = document.Pages.Add();
var rect = new Rectangle(72, 748, 164, 768);
var printButton = new ButtonField(page, rect)
{
    AlternateName = "Print current document",
    Color = Color.Black,
    PartialName = "printBtn1",
    NormalCaption = "Print Document"
};
var border = new Border(printButton)
{
    Style = BorderStyle.Solid,
    Width = 2
};
printButton.Border = border;
printButton.Characteristics.Border =
    System.Drawing.Color.FromArgb(255, 0, 0, 255);
printButton.Characteristics.Background =  
    System.Drawing.Color.FromArgb(255, 0, 191, 255);
document.Form.Add(printButton);

In this example, we set a button name (Name), a tooltip (AlternateName), a label (NormalCaption), and a color of the label text (Color). Additionally, we decorated our button with a border and set a background. Now our button looks like shown in the screenshot below:

Colored button with filled Name and Tooltip properties

Assigning an action to the button

PDF Standard describes various types of actions:

• GoTo — Go to a destination in the current document;
• GoToR (“Go-to remote”) — Go to a destination in another
  document;
• GoToE (“Go-to embedded”) — Go to a destination in
  an embedded file;
• Launch — Launch an application, usually to open a file;
• Thread — Begin reading an article thread;
• URI — Resolve a uniform resource identifier;
• Sound — Play a sound;
• Movie — Play a movie;
• Hide — Set an annotation’s Hidden flag;
• Named — Execute an action predefined by the conforming reader;
• SubmitForm — Send data to a uniform resource locator;
• ResetForm — Set fields to their default values;
• ImportData — Import field values from a file;
• JavaScript — Execute a JavaScript script;
• SetOCGState — Set the states of optional content groups.
• Rendition — Controls the playing of multimedia content;
• Trans — Updates the display of a document, using a transition dictionary.
• GoTo3DView — Set the current view of a 3D annotation.

As you can see, we have too many actions for different purposes, and therefore in this post, we will learn how to use only Named Actions. The use of other types of actions, we will consider in future posts.

The PDF standard describes only 4 named actions (NextPage, PrevPage, FirstPage, LastPage), but in practice, we can use more, for example, Print, Save As, Zoom/Fit Width, etc. To do this we need to set OnActivated property:

var printButton = new ButtonField(page, rect)
{
    AlternateName = "Print current document",
    Color = Color.Black,
    PartialName = "printBtn1",
    NormalCaption = "Print Document",
    OnActivated = new NamedAction(PredefinedAction.File_Print)
};

Using Document-navigation actions

Let's consider the more complex example of the Widget Annotations usage: we will simulate document navigation in PDF document. It can be useful due to different reasons, for example, we want to use a PDF document as a presentation.

In this example, we need to create 4 buttons and therefore we make some preparations at first …

var document = new Document(@"C:\\tmp\\JSON Fundamenals.pdf");
var buttons = new ButtonField[4];
var alternateNames = new[] { "Go to first page", "Go to prev page", "Go to next page", "Go to last page" };
var normalCaptions = new[] { "First", "Prev", "Next", "Last" };
PredefinedAction[] actions = {
PredefinedAction.FirstPage,
PredefinedAction.PrevPage,
PredefinedAction.NextPage,
PredefinedAction.LastPage };
var clrBorder = System.Drawing.Color.FromArgb(255, 0, 255, 0);
var clrBackGround = System.Drawing.Color.FromArgb(255, 0, 96, 70);

… and then will create the buttons, but not attach them to the page.

for (var i = 0; i < 4; i++)
{
    buttons[i] = new ButtonField(document,
           new Rectangle(32 + i * 80, 28, 104 + i * 80, 68))
    {
       AlternateName = alternateNames[i],
       Color = Color.White,
       NormalCaption = normalCaptions[i],
       OnActivated = new NamedAction(actions[i])
    };
    buttons[i].Border = new Border(buttons[i])
    {
       Style = BorderStyle.Solid,
       Width = 2
    };
    buttons[i].Characteristics.Border = clrBorder;
    buttons[i].Characteristics.Background = clrBackGround;
}

At last, we will duplicate this array of buttons on each page in the document.

for (var pageIndex = 1; pageIndex <= document.Pages.Count;
                                                        pageIndex++)
    for (var i = 0; i < 4; i++)
        document.Form.Add(buttons[i], 
          $"btn{pageIndex}_{i + 1}", pageIndex);

We call Form.Add method with the following parameters: field, name, and the index of the pages that this field will be added to.

Finally, we will disable the “First” and “Prev” buttons on the first page and the “Next” and “Last” buttons on the last page.

document.Form["btn1_1"].ReadOnly = true;
document.Form["btn1_2"].ReadOnly = true;
document.Form[$"btn{document.Pages.Count}_3"].ReadOnly = true;
document.Form[$"btn{document.Pages.Count}_4"].ReadOnly = true;

In this example, I use a presentation with 6 slides for and after the button adding it looks like on the screenshot below:

Presentation in PDF with document-navigation buttons.