Foxit PDF SDK

Public Types | Public Member Functions | List of all members
foxit::pdf::Bookmark Class Reference
Inheritance diagram for foxit::pdf::Bookmark:

## Public Types
enum | Position { e_PosFirstChild = 0, e_PosLastChild = 1, e_PosPrevSibling = 2, e_PosNextSibling = 3, e_PosFirstSibling = 4, e_PosLastSibling = 5 }
| Enumeration for bookmark position. More...
enum | Style { e_StyleNormal = 0x00, e_StyleItalic = 0x01, e_StyleBold = 0x02 }
| Enumeration for bookmark style type. More...

## Public Member Functions
| Bookmark (const Bookmark &other)
| Constructor, with another bookmark object. More...
| Bookmark (const PDFDoc &pdf_doc, objects::PDFDictionary *bookmark_dict)
| Constructor, with parameters. More...
| ~Bookmark ()
| Destructor.
actions::Action | GetAction ()
| Get action. More...
RGB | GetColor () const
| Get the color used for displaying title. More...
Destination | GetDestination ()
| Get the destination. More...
objects::PDFDictionary * | GetDict () const
| Get PDF dictionary of current bookmark. More...
Bookmark | GetFirstChild ()
| Get the first child bookmark. More...
Bookmark | GetNextSibling ()
| Get the next sibling bookmark. More...
Bookmark | GetParent ()
| Get the parent bookmark. More...
uint32 | GetStyle () const
| Get the style. More...
WString | GetTitle () const
| Get the title. More...
bool | HasChild ()
| Check if current bookmark has child bookmark(s). More...
Bookmark | Insert (const WString &title, Position position)
| Insert a new bookmark according to the relationship position to current bookmark. More...
bool | IsEmpty () const
| Check whether current object is empty or not. More...
bool | IsFirstChild ()
| Check if current bookmark is the first child of its parent bookmark. More...
bool | IsLastChild ()
| Check if current bookmark is the last child of its parent bookmark. More...
bool | IsRoot ()
| Check if current bookmark is the root bookmark. More...
bool | MoveTo (const Bookmark &dest_bookmark, Position position)
| Move current bookmark to be child or sibling of another bookmark. More...
bool | operator!= (const Bookmark &other) const
| Not equal operator. More...
Bookmark & | operator= (const Bookmark &other)
| Assign operator. More...
bool | operator== (const Bookmark &other) const
| Equal operator. More...
bool | RemoveAction ()
| Remove action. More...
void | SetAction (const actions::Action &action)
| Set action. More...
void | SetColor (RGB color)
| Set the color used for displaying title. More...
void | SetDestination (const Destination &destination)
| Set the destination. More...
void | SetStyle (uint32 style)
| Set the style. More...
void | SetTitle (const WString &title)
| Set the title. More...
Public Member Functions inherited from foxit::Base
FS_HANDLE | Handle () const
| Get the handle of current object. More...

## Detailed Description

PDF bookmark is also called "outline". It's a tree-structured hierarchy. It allows user to navigate PDF document easily by selecting a bookmark. One bookmark contains a destination or actions to indicate how to response when user selects it.
In order to get/set the bookmark tree, function PDFDoc::GetRootBookmark must be called first to get the root of the whole bookmark tree. If the "root bookmark" does not exist, function PDFDoc::CreateRootBookmark could be called to create a new "root bookmark". Here, "root bookmark" is an abstract object. It represents the "Outline" of PDF document. For more details about "Outline", please refer to Section 8.2.3 in PDF Reference 1.7. "root bookmark" can only have some child bookmarks, but no parent, no next sibling bookmarks or any data (including bookmark data, destination data and action data). And "root bookmark" cannot be shown on the application UI since it has no data. So, for a root bookmark, only function Bookmark::GetFirstChild can be used.
From the root bookmark, the bookmark tree can be traversed and each bookmark node can be accessed.
This class offers several functions to get/set other bookmarks from current bookmark. For example:

- To access the parent bookmark, use function Bookmark::GetParent.
- To access the first child bookmark, use function Bookmark::GetFirstChild.
- To access the next sibling bookmark, use function Bookmark::GetNextSibling.
- To Insert a new bookmark, use function Bookmark::Insert.
- To move a bookmark, use function Bookmark::MoveTo.

This class also offers functions to get/set the data of a PDF bookmark.

See also
  PDFDoc

## Member Enumeration Documentation

## ◆ Position

enum foxit::pdf::Bookmark::Position

Enumeration for bookmark position.

Values of this enumeration should be used alone.
Actually, "bookmark position" means the relationship between a bookmark and another bookmark.

Enumerator
e_PosFirstChild | A bookmark is the first child of another specified bookmark.
e_PosLastChild | A bookmark is the last child of another specified bookmark.
e_PosPrevSibling | A bookmark is the previous sibling of another specified bookmark.
e_PosNextSibling | A bookmark is the next sibling of another specified bookmark.
e_PosFirstSibling | A bookmark is the first sibling of another specified bookmark.
e_PosLastSibling | A bookmark is the last sibling of another specified bookmark.

## ◆ Style

enum foxit::pdf::Bookmark::Style

Enumeration for bookmark style type.

Values of this enumeration can be used alone or in combination.

Enumerator
e_StyleNormal | Show bookmark title as normal text.
e_StyleItalic | Show bookmark title as italic text.
e_StyleBold | Show bookmark title as bold text.

## Constructor & Destructor Documentation

## ◆ Bookmark() [1/2]

foxit::pdf::Bookmark::Bookmark | ( | const PDFDoc & | pdf_doc,
|  | objects::PDFDictionary * | bookmark_dict
| ) |  |

Constructor, with parameters.

Parameters

  [in] | pdf_doc | A valid PDF document object.
  [in] | bookmark_dict | A PDF dictionary which represents a bookmark. This PDF dictionary should have existed in the PDF document represented by parameter pdf_doc.

## ◆ Bookmark() [2/2]

foxit::pdf::Bookmark::Bookmark | ( | const Bookmark & | other | ) |

Constructor, with another bookmark object.

Parameters

  [in] | other | Another bookmark object.

## Member Function Documentation

## ◆ GetAction()

actions::Action foxit::pdf::Bookmark::GetAction | ( |  | ) |

Get action.

If current bookmark is returned by function PDFDoc::GetRootBookmark or PDFDoc::CreateRootBookmark, that means it is the "root bookmark", and it does not have any action information. In this case, this function will return an action object which's function actions::Action::IsEmpty returns true.

Returns
  An action object.

## ◆ GetColor()

RGB foxit::pdf::Bookmark::GetColor | ( |  | ) | const

Get the color used for displaying title.

If current bookmark is returned by function PDFDoc::GetRootBookmark or PDFDoc::CreateRootBookmark, that means it is the "root bookmark", and it does not have color. In this case, this function will return 0x000000 by default.

Returns
  The color used for displaying title. Format: 0xRRGGBB.

## ◆ GetDestination()

Destination foxit::pdf::Bookmark::GetDestination | ( |  | ) |

Get the destination.

Bookmark's destination is some place in current document where the bookmark can "goto". If the bookmark cannot "goto" any place in current document, that means no destination information can be retrieved and this function will return a destination object which's function Destination::IsEmpty returns true.
If current bookmark is returned by function PDFDoc::GetRootBookmark or PDFDoc::CreateRootBookmark, that means it is the "root bookmark", and it does not have any destination information. In this case, this function will return a destination object which's function Destination::IsEmpty returns true.

Returns
  The destination object.

## ◆ GetDict()

objects::PDFDictionary* foxit::pdf::Bookmark::GetDict | ( |  | ) | const

Get PDF dictionary of current bookmark.

Returns
  The PDF dictionary. If there is any error, this function will return NULL.

## ◆ GetFirstChild()

Bookmark foxit::pdf::Bookmark::GetFirstChild | ( |  | ) |

Get the first child bookmark.

Returns
  The first child bookmark object.

## ◆ GetNextSibling()

Bookmark foxit::pdf::Bookmark::GetNextSibling | ( |  | ) |

Get the next sibling bookmark.

If current bookmark is returned by function PDFDoc::GetRootBookmark or PDFDoc::CreateRootBookmark, that means it is the "root bookmark", and it does not have any sibling bookmark. In this case, this function will return a bookmark object which's function Bookmark::IsEmpty returns true.

Returns
  The next sibling bookmark object.

## ◆ GetParent()

Bookmark foxit::pdf::Bookmark::GetParent | ( |  | ) |

Get the parent bookmark.

If current bookmark is returned by function PDFDoc::GetRootBookmark or PDFDoc::CreateRootBookmark, that means it is the "root bookmark", and it does not have a parent bookmark. In this case, this function will return a bookmark object which's function Bookmark::IsEmpty returns true.

Returns
  The parent bookmark object.

## ◆ GetStyle()

uint32 foxit::pdf::Bookmark::GetStyle | ( |  | ) | const

Get the style.

If current bookmark is returned by function PDFDoc::GetRootBookmark or PDFDoc::CreateRootBookmark, that means it is the "root bookmark", and it does not have style information. In this case, this function will return Bookmark::e_StyleNormal by default.

Returns
  Value for The bookmark style. Please refer to values starting from Bookmark::e_StyleNormal and this would be one or a combination of these values.

## ◆ GetTitle()

WString foxit::pdf::Bookmark::GetTitle | ( |  | ) | const

Get the title.

If current bookmark is returned by function PDFDoc::GetRootBookmark or PDFDoc::CreateRootBookmark, that means it is the "root bookmark", and it does not have title. In this case, this function will return an empty string.

Returns
  The title string.

## ◆ HasChild()

bool foxit::pdf::Bookmark::HasChild | ( |  | ) |

Check if current bookmark has child bookmark(s).

Returns
  true means current bookmark has child bookmark(s), and false means current bookmark does not have any child bookmark.

## ◆ Insert()

Bookmark foxit::pdf::Bookmark::Insert | ( | const WString & | title,
|  | Position | position
| ) |  |

Insert a new bookmark according to the relationship position to current bookmark.

For the new bookmark, the color would be 0x000000 and the style would be Bookmark::e_StyleNormal by default.

Parameters

  [in] | title | Title string for the new bookmark. It should not be an empty string.
  [in] | position | The position where the new bookmark item is to be inserted, based on current bookmark. Please refer to values starting from Bookmark::e_PosFirstChild and this should be one of these values. If current bookmark is just the "root bookmark", parameter position can only be Bookmark::e_PosFirstChild or Bookmark::e_PosLastChild.

Returns
  A new bookmark object.

## ◆ IsEmpty()

bool foxit::pdf::Bookmark::IsEmpty | ( |  | ) | const

Check whether current object is empty or not.

When the current object is empty, that means current object is useless.

Returns
  true means current object is empty, while false means not.

## ◆ IsFirstChild()

bool foxit::pdf::Bookmark::IsFirstChild | ( |  | ) |

Check if current bookmark is the first child of its parent bookmark.

Returns
  true means current bookmark is the first child of its parent bookmark, while false means not.

## ◆ IsLastChild()

bool foxit::pdf::Bookmark::IsLastChild | ( |  | ) |

Check if current bookmark is the last child of its parent bookmark.

Returns
  true means current bookmark is the last child of its parent bookmark, while false means not.

## ◆ IsRoot()

bool foxit::pdf::Bookmark::IsRoot | ( |  | ) |

Check if current bookmark is the root bookmark.

"root bookmark" is an abstract object. It represents the "Outline" of PDF document. For more details about "Outline", please refer to Section 8.2.3 in PDF Reference 1.7. "root bookmark" can only have some child bookmarks, but no parent, no next sibling bookmarks or any data (including bookmark data, destination data and action data). And "root bookmark" cannot be shown on the application UI since it has no data.

Returns
  true means current bookmark is the root bookmark, while false means not.

## ◆ MoveTo()

bool foxit::pdf::Bookmark::MoveTo | ( | const Bookmark & | dest_bookmark,
|  | Position | position
| ) |  |

Move current bookmark to be child or sibling of another bookmark.

If current bookmark is returned by function PDFDoc::GetRootBookmark or PDFDoc::CreateRootBookmark, that means it is the "root bookmark", and it cannot be moved to be child or sibling of any bookmark in the bookmark tree. In this case, this function will return false directly.

Parameters

  [in] | dest_bookmark | The destination bookmark. It should not be current bookmark itself or any descendant of current bookmark. Current bookmark will be moved to be child or sibling of the destination bookmark.
  [in] | position | The position where the current bookmark is to be moved to, based on parameter destBookmark. Please refer to values starting from Bookmark::e_PosFirstChild and this should be one of these values.

Returns
  true means success, while false means failure.

## ◆ operator!=()

bool foxit::pdf::Bookmark::operator!= | ( | const Bookmark & | other | ) | const

Not equal operator.

Parameters

  [in] | other | Another bookmark object. This function will check if current object is not equal to this one.

Returns
  true means not equal, while false means equal.

## ◆ operator=()

Bookmark& foxit::pdf::Bookmark::operator= | ( | const Bookmark & | other | ) |

Assign operator.

Parameters

  [in] | other | Another bookmark object, whose value would be assigned to current object.

Returns
  Reference to current object itself.

## ◆ operator==()

bool foxit::pdf::Bookmark::operator== | ( | const Bookmark & | other | ) | const

Equal operator.

Parameters

  [in] | other | Another bookmark object. This function will check if current object is equal to this one.

Returns
  true means equal, while false means not equal.

## ◆ RemoveAction()

bool foxit::pdf::Bookmark::RemoveAction | ( |  | ) |

Remove action.

When removing bookmark's action, bookmark's destination will be removed at the same time.
If current bookmark is returned by function PDFDoc::GetRootBookmark or PDFDoc::CreateRootBookmark, that means it is the "root bookmark", and it does not have any action information. In this case, this function will return true directly.

Returns
  true means success, while false means failure.

## ◆ SetAction()

void foxit::pdf::Bookmark::SetAction | ( | const actions::Action & | action | ) |

Set action.

If current bookmark is returned by function PDFDoc::GetRootBookmark or PDFDoc::CreateRootBookmark, that means it is the "root bookmark", and it does not have any action information. In this case, this function will return directly without doing anything.

Parameters

  [in] | action | A valid action to be set. Currently only support following types as the new action: actions::Action::e_TypeGoto, actions::Action::e_TypeURI, actions::Action::e_TypeJavaScript, actions::Action::e_TypeNamed, actions::Action::e_TypeGoToR, actions::Action::e_TypeGoToE, actions::Action::e_TypeSubmitForm, actions::Action::e_TypeResetForm, actions::Action::e_TypeHide, actions::Action::e_TypeLaunch, actions::Action::e_TypeImportData, actions::Action::e_TypeRendition.

Returns
  None.

## ◆ SetColor()

void foxit::pdf::Bookmark::SetColor | ( | RGB | color | ) |

Set the color used for displaying title.

If current bookmark is returned by function PDFDoc::GetRootBookmark or PDFDoc::CreateRootBookmark, that means it is the "root bookmark", and it does not have color. In this case, this function will return directly without doing anything.

Parameters

  [in] | color | New color used for displaying title. Format:0xRRGGBB.

Returns
  None.

## ◆ SetDestination()

void foxit::pdf::Bookmark::SetDestination | ( | const Destination & | destination | ) |

Set the destination.

Bookmark's destination is some place in current document where the bookmark can "goto".
If current bookmark is returned by function PDFDoc::GetRootBookmark or PDFDoc::CreateRootBookmark, that means it is the "root bookmark", and it does not have any destination information. In this case, this function will return directly without doing anything.

Parameters

  [in] | destination | A valid destination.

Returns
  None.

## ◆ SetStyle()

void foxit::pdf::Bookmark::SetStyle | ( | uint32 | style | ) |

Set the style.

If current bookmark is returned by function PDFDoc::GetRootBookmark or PDFDoc::CreateRootBookmark, that means it is the "root bookmark", and it does not have style information. In this case, this function will return directly without doing anything.

Parameters

  [in] | style | New bookmark style. Please refer to values starting from Bookmark::e_StyleNormal and this can be one or a combination of these values. If the style is invalid, Bookmark::e_StyleNormal will be set by default.

Returns
  None.

## ◆ SetTitle()

void foxit::pdf::Bookmark::SetTitle | ( | const WString & | title | ) |

Set the title.

If current bookmark is returned by function PDFDoc::GetRootBookmark or PDFDoc::CreateRootBookmark, that means it is the "root bookmark", and it does not have title. In this case, this function will return directly without doing anything.

Parameters

  [in] | title | New title string. It should not be an empty string.

Returns
  None.