pdftron::PDF::Highlights Class Reference

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:. More...

#include <Highlights.h>

List of all members.

Classes
struct	Highlight
Public Member Functions
	Highlights ()
	Constructor and destructor.
	~Highlights ()
	Highlights (const Highlights &hlts)
Highlights &	operator= (const Highlights &hlts)
	Assignment operator.
void	Load (const UString &file_name)
	Load the Highlight information from a file.
void	Save (const UString &file_name)
	Save the current Highlight information in the class to a file.
void	Add (const Highlights &hlts)
	Add highlights.
void	Clear ()
	Clear the current Highlight information in the class.
void	Begin (PDFDoc &doc)
	Rewind the internal pointer to the first highlight.
bool	HasNext () const
	Query if there is any subsequent highlight after the current highlight.
void	Next ()
	Move the current highlight to the next highlight.
int	GetCurrentPageNumber () const
	Get the page number of the current highlight.
int	GetCurrentQuads (const double *&quads) const
	Get the corresponding quadrangles of the current highlight.
void	Destroy ()
	Frees the native memory of the object.

---

Detailed Description

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::SelectByHighlights() 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 TextSearchTest sample project.

---

Constructor & Destructor Documentation

pdftron::PDF::Highlights::Highlights

(

)

Constructor and destructor.

pdftron::PDF::Highlights::~Highlights

(

)

pdftron::PDF::Highlights::Highlights

(

const Highlights &

hlts

)

---

Member Function Documentation

Highlights& pdftron::PDF::Highlights::operator=

(

const Highlights &

hlts

)

Assignment operator.

void pdftron::PDF::Highlights::Load

(

const UString &

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.

void pdftron::PDF::Highlights::Save

(

const UString &

file_name

)

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

Parameters:

file_name

the name of the file to save to.

void pdftron::PDF::Highlights::Add

(

const Highlights &

hlts

)

Add highlights.

Parameters:

hlts

the Highlights instance containing the highlights to be added.

void pdftron::PDF::Highlights::Clear

(

)

Clear the current Highlight information in the class.

void pdftron::PDF::Highlights::Begin

(

PDFDoc &

doc

)

Rewind the internal pointer to the first highlight.

Parameters:

doc

the PDF document to which the highlights correspond.

Note:

the PDF document can be a dummy document unless GetCurrentQuads() is to be called.

bool pdftron::PDF::Highlights::HasNext

(

)

const

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

void pdftron::PDF::Highlights::Next

(

)

Move the current highlight to the next highlight.

int pdftron::PDF::Highlights::GetCurrentPageNumber

(

)

const

Get the page number of the current highlight.

int pdftron::PDF::Highlights::GetCurrentQuads

(

const double *&

quads

)

const

Get the corresponding quadrangles of the current highlight.

Parameters:

quads

the output pointer to the resulting quadrangles.

Returns:

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

Note:

the 'quads' array is owned by the current Highlights and does not need to be explicitly released. 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.

void pdftron::PDF::Highlights::Destroy

(

)

Frees the native memory of the object.