pdftron::PDF::Bookmark Class Reference

A PDF document may optionally display a document outline on the screen, allowing the user to navigate interactively from one part of the document to another. More...

#include <Bookmark.h>

List of all members.

Public Member Functions

 Bookmark ()
 A constructor.
 Bookmark (SDF::Obj in_bookmark_dict)
 A constructor.
 Bookmark (const Bookmark &in_bookmark)
 Copy constructor.
Bookmarkoperator= (const Bookmark &in_bookmark)
 Sets this Bookmark object equal to the specified Bookmark object.
bool operator== (const Bookmark &in_bookmark)
 Compares two Bookmark objects for equality.
bool IsValid () const
 Indicates whether the Bookmark is valid (non-null).
bool HasChildren ()
 Indicates whether the Bookmark has children.
Bookmark GetNext ()
 Returns the Bookmark's next (right) sibling.
Bookmark GetPrev ()
 Returns the Bookmark's previous (left) sibling.
Bookmark GetFirstChild ()
 Returns the Bookmark's first child.
Bookmark GetLastChild ()
 Returns the Bookmark's last child.
Bookmark GetParent ()
 Returns the Bookmark's parent Bookmark.
Bookmark Find (const UString &in_title)
 Returns the Bookmark specified by the given title string.
Bookmark AddChild (const UString &in_title)
 Adds a new Bookmark as the new last child of this Bookmark.
void AddChild (Bookmark in_bookmark)
 Adds the specified Bookmark as the new last child of this Bookmark.
Bookmark AddNext (const UString &in_title)
 Adds a new Bookmark to the tree containing this Bookmark, as the new right sibling.
void AddNext (Bookmark in_bookmark)
 Adds the specified Bookmark as the new right sibling to this Bookmark, adjusting the tree containing this Bookmark appropriately.
Bookmark AddPrev (const UString &in_title)
 Adds a new Bookmark to the tree containing this Bookmark, as the new left sibling.
void AddPrev (Bookmark in_bookmark)
 Adds the specified Bookmark as the new left sibling to this Bookmark, adjusting the tree containing this Bookmark appropriately.
void Delete ()
 Removes the Bookmark's subtree from the bookmark tree containing it.
void Unlink ()
 Unlinks this Bookmark from the bookmark tree that contains it, and adjusts the tree appropriately.
int GetIndent ()
 Returns the indentation level of the Bookmark in its containing tree.
bool IsOpen ()
 Indicates whether the Bookmark is open.
void SetOpen (bool in_open)
 Opens or closes the Bookmark.
int GetOpenCount ()
 Returns the number of opened bookmarks in this subtree.
UString GetTitle ()
 Returns the Bookmark's title string.
SDF::Obj GetTitleObj ()
 Returns the Bookmark's title string object.
void SetTitle (const UString &title)
 Sets the Bookmark’s title string.
Action GetAction ()
 Returns the Bookmark's action.
void SetAction (Action in_action)
 Sets the Bookmark’s action.
void RemoveAction ()
 Removes the Bookmark’s action.
int GetFlags ()
 Returns the Bookmark's flags.
void SetFlags (int in_flags)
 Sets the Bookmark's flags.
void GetColor (double &out_r, double &out_g, double &out_b)
 Returns the Bookmark's RGB color value.
void SetColor (double in_r=0.0, double in_g=0.0, double in_b=0.0)
 Sets the Bookmark's color value.
SDF::Obj GetSDFObj () const
 Returns the underlying SDF/Cos object.

Static Public Member Functions

static Bookmark Create (class PDFDoc &in_doc, const UString &in_title)
 Creates a new valid Bookmark with given title in the specified document.


Detailed Description

A PDF document may optionally display a document outline on the screen, allowing the user to navigate interactively from one part of the document to another.

The outline consists of a tree-structured hierarchy of Bookmarks (sometimes called outline items), which serve as a 'visual table of contents' to display the document’s structure to the user.

Each Bookmark has a title that appears on screen, and an Action that specifies what happens when a user clicks on the Bookmark. The typical action for a user-created Bookmark is to move to another location in the current document, although any action (see PDF::Action) can be specified.

Bookmark is a utility class used to simplify work with PDF bookmarks (or outlines; see section 8.2.2 'Document Outline' in PDF Reference Manual for more details).


Constructor & Destructor Documentation

pdftron::PDF::Bookmark::Bookmark (  ) 

A constructor.

Creates a null (non-valid) bookmark.

pdftron::PDF::Bookmark::Bookmark ( SDF::Obj  in_bookmark_dict  ) 

A constructor.

Creates a Bookmark and initialize it using given Cos/SDF object.

Parameters:
in_bookmark_dict Pointer to the Cos/SDF object (outline item dictionary).
Returns:
The new Bookmark.
Note:
The constructor does not copy any data, but is instead the logical equivalent of a type cast.

pdftron::PDF::Bookmark::Bookmark ( const Bookmark in_bookmark  ) 

Copy constructor.

Creates a copy of the given Bookmark object.

Parameters:
in_bookmark A reference to an existing Bookmark object.
Returns:
The new Bookmark.


Member Function Documentation

static Bookmark pdftron::PDF::Bookmark::Create ( class PDFDoc in_doc,
const UString in_title 
) [static]

Creates a new valid Bookmark with given title in the specified document.

Parameters:
in_doc The document in which a Bookmark is to be created.
in_title The title string value of the new Bookmark.
Returns:
The new Bookmark.
Note:
The new Bookmark is not linked to the outline tree. Use AddChild()/AddNext()/AddPrev() methods in order to link the Bookmark to the outline tree

Bookmark& pdftron::PDF::Bookmark::operator= ( const Bookmark in_bookmark  ) 

Sets this Bookmark object equal to the specified Bookmark object.

Parameters:
in_bookmark Reference to a Bookmark object that is assigned to this Bookmark object.
Returns:
This method returns a reference to this Bookmark object to allow cascaded assignments.

bool pdftron::PDF::Bookmark::operator== ( const Bookmark in_bookmark  ) 

Compares two Bookmark objects for equality.

Parameters:
in_bookmark A reference to an existing Bookmark object.
Returns:
True if the both Bookmarks share the same underlying SDF/Cos object; otherwise false.

bool pdftron::PDF::Bookmark::IsValid (  )  const

Indicates whether the Bookmark is valid (non-null).

Returns:
True if this is a valid (non-null) Bookmark; otherwise false.
Note:
If this method returns false the underlying SDF/Cos object is null and the Bookmark object should be treated as null as well.

bool pdftron::PDF::Bookmark::HasChildren (  ) 

Indicates whether the Bookmark has children.

Returns:
True if the Bookmark has children; otherwise false.

Bookmark pdftron::PDF::Bookmark::GetNext (  ) 

Returns the Bookmark's next (right) sibling.

Returns:
the Bookmark’s next (right) sibling.

Bookmark pdftron::PDF::Bookmark::GetPrev (  ) 

Returns the Bookmark's previous (left) sibling.

Returns:
The Bookmark’s previous (left) sibling.

Bookmark pdftron::PDF::Bookmark::GetFirstChild (  ) 

Returns the Bookmark's first child.

Returns:
The Bookmark’s first child.

Bookmark pdftron::PDF::Bookmark::GetLastChild (  ) 

Returns the Bookmark's last child.

Returns:
The Bookmark’s last child.

Bookmark pdftron::PDF::Bookmark::GetParent (  ) 

Returns the Bookmark's parent Bookmark.

Returns:
The Bookmark’s parent Bookmark.

Bookmark pdftron::PDF::Bookmark::Find ( const UString in_title  ) 

Returns the Bookmark specified by the given title string.

Parameters:
in_title The title string value of the Bookmark to find.
Returns:
A Bookmark matching the title string value specified.

Bookmark pdftron::PDF::Bookmark::AddChild ( const UString in_title  ) 

Adds a new Bookmark as the new last child of this Bookmark.

Parameters:
in_title The title string value of the new Bookmark.
Returns:
The newly created child Bookmark.
Note:
If this Bookmark previously had no children, it will be open after the child is added.

void pdftron::PDF::Bookmark::AddChild ( Bookmark  in_bookmark  ) 

Adds the specified Bookmark as the new last child of this Bookmark.

Parameters:
in_bookmark The Bookmark object to be added as a last child of this Bookmark.
Note:
Parameter in_bookmark must not be linked to a bookmark tree.

If this Bookmark previously had no children, it will be open after the child is added.

Bookmark pdftron::PDF::Bookmark::AddNext ( const UString in_title  ) 

Adds a new Bookmark to the tree containing this Bookmark, as the new right sibling.

Parameters:
in_title The title string value of the new Bookmark.
Returns:
The newly created sibling Bookmark.

void pdftron::PDF::Bookmark::AddNext ( Bookmark  in_bookmark  ) 

Adds the specified Bookmark as the new right sibling to this Bookmark, adjusting the tree containing this Bookmark appropriately.

Parameters:
in_bookmark The Bookmark object to be added to this Bookmark.
Note:
Parameter in_bookmark must not be linked to a bookmark tree.

Bookmark pdftron::PDF::Bookmark::AddPrev ( const UString in_title  ) 

Adds a new Bookmark to the tree containing this Bookmark, as the new left sibling.

Parameters:
in_title The title string value of the new Bookmark.
Returns:
The newly created sibling Bookmark.

void pdftron::PDF::Bookmark::AddPrev ( Bookmark  in_bookmark  ) 

Adds the specified Bookmark as the new left sibling to this Bookmark, adjusting the tree containing this Bookmark appropriately.

Parameters:
in_bookmark The Bookmark object to be added to this Bookmark.
Note:
Parameter in_bookmark must not be linked to a bookmark tree.

void pdftron::PDF::Bookmark::Delete (  ) 

Removes the Bookmark's subtree from the bookmark tree containing it.

void pdftron::PDF::Bookmark::Unlink (  ) 

Unlinks this Bookmark from the bookmark tree that contains it, and adjusts the tree appropriately.

Note:
After the bookmark is unlinked is can be moved to another place in the bookmark tree located in the same document.

int pdftron::PDF::Bookmark::GetIndent (  ) 

Returns the indentation level of the Bookmark in its containing tree.

Returns:
The indentation level of the Bookmark in its containing tree.
Note:
The root level has an indentation level of zero.

bool pdftron::PDF::Bookmark::IsOpen (  ) 

Indicates whether the Bookmark is open.

Returns:
True if this Bookmark is open; otherwise false.
Note:
An open Bookmark shows all its children.

void pdftron::PDF::Bookmark::SetOpen ( bool  in_open  ) 

Opens or closes the Bookmark.

Parameters:
in_open Boolean value that contains the status. If true, the Bookmark is opened. Otherwise the Bookmark is closed.
Note:
An opened Bookmark shows its children, while a closed Bookmark does not.

int pdftron::PDF::Bookmark::GetOpenCount (  ) 

Returns the number of opened bookmarks in this subtree.

Returns:
The number of opened bookmarks in this subtree (not including this Bookmark). If the item is closed, a negative integer whose absolute value specifies how many descendants would appear if the item were reopened.

UString pdftron::PDF::Bookmark::GetTitle (  ) 

Returns the Bookmark's title string.

Returns:
The Bookmark’s title string).

SDF::Obj pdftron::PDF::Bookmark::GetTitleObj (  ) 

Returns the Bookmark's title string object.

Returns:
The Bookmark's title string object.

void pdftron::PDF::Bookmark::SetTitle ( const UString title  ) 

Sets the Bookmark’s title string.

Parameters:
title The new title string for the bookmark.

Action pdftron::PDF::Bookmark::GetAction (  ) 

Returns the Bookmark's action.

Returns:
The Bookmark’s action.

void pdftron::PDF::Bookmark::SetAction ( Action  in_action  ) 

Sets the Bookmark’s action.

Parameters:
in_action The new Action for the Bookmark.

void pdftron::PDF::Bookmark::RemoveAction (  ) 

Removes the Bookmark’s action.

int pdftron::PDF::Bookmark::GetFlags (  ) 

Returns the Bookmark's flags.

Returns:
The flags of the Bookmark object. Bit 1 (least-significant bit) indicates italic font whereas bit 2 indicates bold font. Therefore, 0 indicates normal, 1 is italic, 2 is bold, and 3 is bold-italic.

void pdftron::PDF::Bookmark::SetFlags ( int  in_flags  ) 

Sets the Bookmark's flags.

Parameters:
in_flags The new bookmark flags. Bit 1 (the least-significant bit) indicates italic font whereas bit 2 indicates bold font. Therefore, 0 indicates normal, 1 is italic, 2 is bold, and 3 is bold-italic.

void pdftron::PDF::Bookmark::GetColor ( double &  out_r,
double &  out_g,
double &  out_b 
)

Returns the Bookmark's RGB color value.

Parameters:
out_r Reference to a variable that receives the red component of the color.
out_g Reference to a variable that receives the green component of the color.
out_b Reference to a variable that receives the blue component of the color.
Note:
The three numbers out_r, out_g, and out_b are in the range 0.0 to 1.0, representing the components in the DeviceRGB color space of the color to be used for the Bookmark’s text.
Example:
   double red, green, blue; 
   bookmark.GetColor(red, green, blue);

void pdftron::PDF::Bookmark::SetColor ( double  in_r = 0.0,
double  in_g = 0.0,
double  in_b = 0.0 
)

Sets the Bookmark's color value.

Parameters:
in_r The red component of the color.
in_g The green component of the color.
in_b The blue component of the color.
Note:
The three numbers in_r, in_g, and in_b are in the range 0.0 to 1.0, representing the components in the DeviceRGB color space of the color to be used for the Bookmark's text. Default color value is black, [0.0 0.0 0.0].

SDF::Obj pdftron::PDF::Bookmark::GetSDFObj (  )  const

Returns the underlying SDF/Cos object.

Returns:
The underlying SDF/Cos object.
Note:
A null (non-valid) bookmark returns a null object.


© 2002-2010 PDFTron Systems Inc.