TonicPoint® Filter

Table of Contents >> Implementing the `TextHandler` Interface

Working with the `TextHandler` Interface

Introduction

The TonicPoint Filter API provides a simple-to-use, event-based mechanism for processing text in PowerPoint documents. To use this API, there are just two steps:

Implement a TextHandler
Use a TextExtractor to process a document with your handler

This tutorial looks at these two steps in more detail.

Background

There are three basic types of text within a PowerPoint document.

Text that occurs inside shapes
Text that appears as WordArt, and,
Text that is defined as Alternative Text

Text that occurs inside a shape is usually considered "normal" text. A shape can be a Placeholder, an AutoShape, a Comment or a Text Box. If a shape is a Placeholder then it has an associated placeholder type. The placeholder type defines how the text is used, e.g. the text is a title. WordArt text is explicitly created using WordArt objects. Alternative text is non-visible text that is associated with a shape using the Web tab in PowerPoint's Format <shape>... dialog, where <shape> is a Placeholder, AutoShape, Comment, Text Box or WordArt depending on the shape with the alternative text.

Each of the three text types can occur in regular slides, master slides or in slide notes.

In addition, document properties also contain text. The standard document properties are all text based: Author, Comments, Company, Keywords, Manager, Subject and Title. Custom properties may be text based (i.e. String's) or at least have text equivalent values through the toString() method (for Dates, Booleans and Numbers).

`TextHandler Interface`

The TextHandler interface defines call-back methods to process text occurring in all of these situations. The processing proceeds as follows.

The method startPresentation(Map standardProps, Map customProps) is called first to allow processing of document properties and perform any set-up inside the text handler.

For each master slide in the document, the method startMaster is called. If there are multiple slide masters, they are processed in the order they appear in the presentation. Title masters are processed immediately after their associated slide master. If the interface implementor has signalled interest in processing the text within a given master, by returning true, then the text contained in the master slide is processed using each of handleText, handleWordArt, and handleAltText as appropriate.

The presentation slides are processed next. For each slide, startSlide is called in the order of the slides in the presentation. Again if the interface implementor has signalled interest in processing the text, the handle text family of methods is invoked for each text item on the slide.

The presentation notes are processed after all the slides. For each slide with notes, startNotes is called. The notes are also processed in presentation order, but be aware that startNotes is only called for slides with notes, so there may be gaps for slides without notes. However you can easily determine to which slide the notes belong through the argument to startNotes.

After all slides and notes are processed, endPresentation is called to allow any clean up.

The handle text methods are called in z-order from bottom to top. i.e. text that logically overlays other text is called last. However each of the handle text methods has the coordinates of the enclosing rectangle as an argument, so the position of the text on the slide can be easily determined.

Table of Contents >> Implementing the `TextHandler` Interface