Summary: Ctors | Methods | Inherited Methods | [Expand All]
public class

# Highlights

extends Object
implements AutoCloseable

java.lang.Object
↳ | com.pdftron.pdf.Highlights

## Class Overview

`Highlights` is used to store the necessary information and perform certain tasks in accordance with Adobe's Highlight standard, whose details can be found at http://partners.adobe.com/public/developer/en/pdf/HighlightFileFormat.pdf.

In a nutshell, the `Highlights` class maintains a set of highlights. Each highlight contains three pieces of information:

- page: the number of the page this Highlight is on;
- position: the start position (text offset) of this Highlight;
- length: the length of this Highlight.

Possible use case scenarios for Highlights include:

- Load a Highlight file (in XML format) and highlight the corresponding texts in the viewer (e.g., if the viewer is implemented using PDFViewCtrl, it can be achieved simply by calling PDFViewCtrl.selectWithHighlights(Highlights highlights) method);
- Save the Highlight information (e.g., constructed by the `TextSearch` class) to an XML file for external uses.

Note:
- The `Highlights` class does not maintain the corresponding PDF document for its highlights. It is the user's responsibility to match them up.
- The `Highlights` class ensures that each highlight it maintains is unique (no two highlights have the same page, position and length values).
- The current implementation of `Highlights` only supports the 'characters' encoding for 'units' as described in the format; the 'words' encoding is not supported at this point.

For a sample code, please take a look at the TextSearch sample project.

## Summary

Public Constructors
| Highlights() Instantiate default highlights.
| Highlights(long other_impl)

Public Methods
void | add(Highlights hlts) Add extra Highlight information into the class.
void | begin(PDFDoc doc) Rewind the internal pointer to the first highlight.
void | clear() Clear the current Highlight information in the class.
void | close() Frees the native memory of the object.
void | destroy() Frees the native memory of the object.
int | getCurrentPageNumber() Get the page number of the current highlight.
double[] | getCurrentQuads() Get the corresponding quadrangles of the current highlight.
TextRange | getCurrentTextRange() Get a `TextRange` object that represents the current highlight.
boolean | hasNext() Query if there is any subsequent highlight after the current highlight.
void | load(String file_name) Load the Highlight information from a file.
void | next() Move the current highlight to the next highlight.
void | save(String file_name) Save the current Highlight information in the class to a file.
String | saveToString() Save the current Highlight information in the class to an XML string.

[Expand] Inherited Methods
From class java.lang.Object
boolean | equals(Object arg0)
final Class<?> | getClass()
int | hashCode()
final void | notify()
final void | notifyAll()
String | toString()
final void | wait(long arg0, int arg1)
final void | wait(long arg0)
final void | wait()
From interface java.lang.AutoCloseable
abstract void | close()

## Public Constructors

#### public Highlights ()

Instantiate default highlights.

#### public Highlights (long other_impl)

## Public Methods

#### public void add (Highlights hlts)

Add extra Highlight information into the class.

##### Parameters

hlts | the Highlights of which the Highlight information is to be added.

#### public void begin (PDFDoc doc)

Rewind the internal pointer to the first highlight.

Note: the PDF document can be a dummy document unless `getCurrentQuads()` is to be called.

##### Parameters

doc | the PDF document to which the highlights correspond.

#### public void clear ()

Clear the current Highlight information in the class.

#### public void close ()

Frees the native memory of the object. This can be explicity called to control the deallocation of native memory and avoid situations where the garbage collector does not free the object in a timely manner.

#### public void destroy ()

Frees the native memory of the object. This can be explicity called to control the deallocation of native memory and avoid situations where the garbage collector does not free the object in a timely manner.

#### public int getCurrentPageNumber ()

Get the page number of the current highlight.

##### Returns

- the current page number

#### public double[] getCurrentQuads ()

Get the corresponding quadrangles of the current highlight.

Note: since a highlight may correspond to multiple quadrangles, e.g., when it crosses a line, the number of resulting quadrangles may be larger than 1.

##### Returns

- the output quadrangles. Each quadrangle has eight doubles (x1, y1), (x2, y2), (x3, y3), (x4, y4) denoting the four vertices in counter-clockwise order.

#### public TextRange getCurrentTextRange ()

Get a `TextRange` object that represents the current highlight.

##### Returns

- the current text range.

#### public boolean hasNext ()

Query if there is any subsequent highlight after the current highlight.

##### Returns

- `true`, if there is subsequent highlight

#### public void load (String file_name)

Load the Highlight information from a file. Note that the pre-existing Highlight information is discarded.

##### Parameters

file_name | the name of the file to load from.

#### public void next ()

Move the current highlight to the next highlight.

#### public void save (String file_name)

Save the current Highlight information in the class to a file.

##### Parameters

file_name | the name of the file to save to.

#### public String saveToString ()

Save the current Highlight information in the class to an XML string.

##### Returns

- the highlight XML file contents as a string