Modifying XPS page on events | Java

Understanding the event-based approach in programming

The event-based approach in programming is a paradigm focused on events and their handling. In this model, the program’s flow is dictated by events, which can include user actions (such as mouse clicks or key presses), notifications generated by the system, or messages from other applications. Below are some key aspects of the event-based approach:

• Events: Events signify important occurrences within a program. These can encompass user interactions, data changes, or messages from different components of a system. For instance, a button click or the loading of a file can trigger events.

• Event Listeners: To handle events, programmers employ event listeners (or handlers). These are functions or methods designated to run when a particular event occurs. For example, an event listener can be configured to execute a function when a user clicks a button.

• Asynchronous Execution: The event-based model typically facilitates asynchronous programming, enabling programs to maintain responsiveness while awaiting events. For instance, a web application can keep functioning as it waits for data from a server.

• Decoupling: The event-based approach encourages decoupling among various components of a program. These components can interact through events without requiring knowledge of each other’s implementation details, resulting in more modular and maintainable code.

• Common Use Cases: Event-driven programming is commonly employed in graphical user interfaces (GUIs), web applications, and systems that necessitate real-time interactions. Frameworks and libraries such as Node.js, React, and many others leverage event-driven patterns.

• State Management: In an event-driven system, effective state management is essential, as the application can exist in various states depending on user interactions or events. Appropriate state management strategies are typically implemented to ensure that the application functions as intended.

Overall, the event-based approach is an effective method for managing interactions and workflows within a program, making it especially suitable for applications that demand responsiveness and user interactions.

The XPS document conversion and events

When you need to modify a specific page of an XPS document using the Aspose.Page API, you typically select the active document (if there are multiple documents in the XPS file), select the active page, and then apply the changes.

Now, let’s say you need to implement repeating changes across all pages in an XPS file and subsequently convert the result to either PDF or an image format. Examples of such changes might include adding a watermark to the pages or inserting navigation hyperlinks. The straightforward method for making such changes involves traversing through the documents in the XPS package, traversing through the pages in the current active document, and then, finally, applying your changes. Thus, the code to achieve this task would look as follows:

for (int i = 1; i <= document.getDocumentCount(); i++)
{
    document.selectActiveDocument(i);
    for (j = 1; j <= document.getPageCount(); j++)
    {
        document.selectActivePage(j);
        // Your changes ...
    }
}
document.saveAsPdf("file-name.pdf", saveOptions);

If you also need to make some irregular changes before applying the repeating ones, this approach may lead to confusion or excessive traversals through documents and pages. Also, these loops may appear somewhat cumbersome.

When you convert an XPS document to PDF or an image, the process occurs one page at a time. As the conversion job prepares to process the next page, it triggers a “before-page” event. User can define the behavior (event handling) on such events by extending the BeforePageSavingEventHandler class, thereby leveraging some of the advantages discussed in the introductory section of this article.

Example of adding navigation hyperlinks

In this section, we will present an example involving navigation hyperlinks. And to make the task a little more complicated, we will convert only a subset of all pages to PDF, as defined by the PdfSaveOptions.setPageNumbers() method.

The event handler class

Below is the extension of the BeforePageSavingEventHandler class:

/**
 * The class to handle the before-page event while converting an XPS document.
 */
public static class NavigationInjector extends BeforePageSavingEventHandler
{
    private final XpsFont _font;
    private List<Integer> _pageNumbers;

    public NavigationInjector(XpsFont font, int[] pageNumbers)
    {
        _font = font;
        if (pageNumbers == null || pageNumbers.length == 0)
            return;

        // Turn the page number array into a sorted collection of unique values.
        SortedMap<Integer, Integer> map = new TreeMap<Integer, Integer>();
        for (int pn : pageNumbers)
            map.put(pn, 0);
        _pageNumbers = new ArrayList<Integer>(map.keySet());
    }

    /**
     * The action itself to be triggered on a before-page event.
     * @param args The even arguments.
     */
    @Override
    public void handle(BeforeSavingEventArgs<PageAPI> args)
    {
        PageAPI api = args.getElementAPI();

        XpsGlyphs glyphs;
        // For all pages in the output PDF except the first one...
        if (args.getOutputPageNumber() > 1)
        {
          // ...insert a hyperlink to the first page...
            glyphs = api.createGlyphs(_font, 15f, 5f, api.getHeight() - 10f, "[First]");
            glyphs.setFill(api.createSolidColorBrush(Color.BLUE));
            glyphs.setHyperlinkTarget(new XpsPageLinkTarget(_pageNumbers == null ? 1 : _pageNumbers.get(0)));
            api.add(glyphs);

            // ...and to the previous page.
            glyphs = api.createGlyphs(_font, 15f, 60f, api.getHeight() - 10f, "[Prev]");
            glyphs.setFill(api.createSolidColorBrush(Color.BLUE));
            glyphs.setHyperlinkTarget(new XpsPageLinkTarget(
                _pageNumbers == null ? args.getAbsolutePageNumber() - 1 : _pageNumbers.get(args.getOutputPageNumber() - 2)));
            api.add(glyphs);
        }

        // For all pages in the output PDF except the last one...
        if ((_pageNumbers != null && args.getOutputPageNumber() < _pageNumbers.size()) ||
            (_pageNumbers == null && args.getOutputPageNumber() < api.getTotalPageCount()))
        {
          // ...insert a hyperlink to the next page...
            glyphs = api.createGlyphs(_font, 15f, 110f, api.getHeight() - 10f, "[Next]");
            glyphs.setFill(api.createSolidColorBrush(Color.BLUE));
            glyphs.setHyperlinkTarget(new XpsPageLinkTarget(
                _pageNumbers == null ? args.getAbsolutePageNumber() + 1 : _pageNumbers.get(args.getOutputPageNumber())));
            api.add(glyphs);

            // ...and to the last page.
            glyphs = api.createGlyphs(_font, 15f, 160f, api.getHeight() - 10f, "[Last]");
            glyphs.setFill(api.createSolidColorBrush(Color.BLUE));
            glyphs.setHyperlinkTarget(new XpsPageLinkTarget(
                _pageNumbers == null ? api.getTotalPageCount() : _pageNumbers.get(_pageNumbers.size() - 1)));
            api.add(glyphs);
        }

        // Insert a page number in the bottom-right corner.
        glyphs = api.createGlyphs(_font, 15f, api.getWidth() - 20f, api.getHeight() - 10f, Integer.toString(args.getOutputPageNumber()));
        glyphs.setFill(api.createSolidColorBrush(Color.BLACK));
        api.add(glyphs);

        // Add an outline entry to display the links to the converted pages in the navigation pane of a PDF viewer.
        api.addOutlineEntry(MessageFormat.format("Page {0}", args.getOutputPageNumber()), 1, args.getAbsolutePageNumber());
    }
}

The handler class needs to be aware of the pages we intend to save as PDF in order to establish the correct hyperlink targets. Consequently, the constructor should take the options’ getPageNumbers() array property as an argument. If the array of page numbers is provided, we create a sorted collection of them, excluding duplicates at the same time. Additionally, the class needs an XpsFont object that contains the font data for the hyperlink text.

The overridden handle() method is where it all happens. The method’s argument is an object that contains the modification API for the current page, the document number within the XPS package, the absolute page number across all documents, the relative page number within the current document (which is equal to the previous number if there is only one document in the package), and the output page number (which is equal to the absolute page number when we convert the entire package).

The logic of the following two if blocks is quite simple. It analyses the getOutputPageNumber() event argument to omit some of the links where appropriate: the [First] and [Prev] links will not be added to the first page, while the [Next] and [Last] links will not appear on the last page. The logic is also designed to accommodate both scenarios, whether page numbers are specified or not.

Following the if blocks, there is code that adds a page number in the bottom-right corner of the page.

The last line adds the page’s outline entry, which is the item that will be displayed in the navigation pane of a PDF viewer (if supported).

Code for conversion

Now that the “before-page” event handler is defined, we can write the code for document conversion:

// For complete examples and data files, please go to https://github.com/aspose-page/Aspose.Page-for-Java
// The path to the documents directory.
String dataDir = Utils.getDataDir();
String fontDir = dataDir + "necessary_fonts/";
// Open an XPS Document
final XpsDocument doc = new XpsDocument(dataDir + "Sample3.xps");
try {
  // Create a font
  final InputStream fontStream = new FileInputStream(fontDir + "arialbd.ttf");
  try {
    // Create options for conversion to PDF
    PdfSaveOptions options = new PdfSaveOptions();
    // Set the filter for the pages that need conversion
    options.setPageNumbers(new int[] { 2, 6, 7, 13 });
    // Add the event handler that will execute right before the conversion of each page
    options.getBeforePageSavingEventHandlers().add(new NavigationInjector(doc.createFont(fontStream), options.getPageNumbers()));
    // Save resultant XPS document
    doc.saveAsPdf(dataDir + "ModifyPageOnConversion_out.pdf", options);
  } finally {
    if (fontStream != null)
      fontStream.close();
  }
} finally {
  if (doc != null)
    doc.close();
}

We open an XPS file and then create a stream object with the font data file. Next, we instantiate the PdfSaveOptions class and specify the page numbers we need to convert. The following line “connects” the “before-page” event handler to the conversion job via the getBeforePageSavingEventHandlers() collection.

All that’s left to do now is run the conversion to PDF using the document’s saveAsPdf() method.

Conclusion

In this article, we covered the fundamental aspects of the event-based approach in programming, examined the direct method for modifying pages of an XPS document, and explored a more advanced technique for making repeating changes to all output pages during the conversion process, using the insertion of navigation hyperlinks as an example.

For the complete examples, explore our Example project.