CIB pdf toolbox technical guide (EN)

9. Adding and removing bookmarks

(from CIB pdf toolbox 1.6.116 onwards)

Using CIB pdf toolbox Join, bookmarks (or outlines) in PDF documents can be added or removed. This can be done with the following properties:

Property description

Type

Functionality

Kind

OutlinesDeleteExisting

String

Remove all outlines or bookmarks from input documents.

Possible values:

„0“: The existing outlines will not be removed. (default)

„1“: All existing outlines will be removed.

Set

OutlinesAdd

String

Adding new outlines and bookmarks to the output PDF document. If bookmarks already exist and should be kept (i.e. OutlinesDeleteExisting=0), the new bookmarks are added to the existing ones.

Possible values:

„ “: No outlines will be added. (default)

A non-empty string: The outlines specified in this property are inserted into the output PDF.                                                        If the syntax is incorrect: error code 349 (CIBPDF_ERROR_OUTLINES_ADD_WRONG_FORMAT)
 

Syntax:

<outlinelist> ::= <outline> | <outline> “;” <outlinelist>

<outline> ::= <outline-with-descendants> | <outline-without-descendants>

<outline-with-descendants> ::= “{” <page> “;{” <destination> “};” <outlinetext> “;{” <outlinedescendants> “}}”

<outline-without-descendants> ::= “{” <page> “;{” <destination> “};” <outlinetext> “}” | “{” <page> “;{” <destination> “};” <outlinetext> “;{}}”

<page> ::= <Integer>

<outlinetext> ::= <text>

<outlinedescendants> ::= <outlinelist>

<destination> ::= <XYZ> | <Fit> | <FitH> | <FitV> | <FitR> | <FitB> | <FitBH> | <FitBV>

<XYZ> ::= „XYZ“ „;“ <Integer> „;“ <Integer> „;“ <Integer>

<Fit> ::= “Fit”

<FitH> ::= “FitH” “;” <Integer>

<FitV> ::= „FitV“ „;“ <Integer>

<FitR> ::= „FitR“ „;“ <Integer> „;“ <Integer> „;“ <Integer> „;“ <Integer>

<FitB> ::= „FitB“

<FitBH> ::= „FitBH“ „;“ <Integer>

<FitBV> ::= „FitBV“ „;“ <Integer>

See next sections for details and examples.

Set

(from CIB pdf toolbox 1.10.0 onwards)

 

Property returns a string with identical structure.

Get



Syntax of OutlinesAdd

One or more bookmarks (outlines) can be inserted in the OutlinesAdd string property.

Syntax:

Outline1;Outline2;...;Outline3

Outlinen:  {page number;{view};text;{subbookmarks}}


Page number

A positive integer that indicates to which page the bookmark points.

E.g. “7”: The bookmark refers to page 7 of the output document.
Especially when using Join to combine several input PDFs to one output document, it is important that the page number refers to the joined output document
.


View

A string that determines which part of the page should be displayed with which zoom factor. There are eight different types of this "view".

These are described in the following table. Number1, Number2, Number3 and Number4 are all non-negative integer numbers. “Window" refers to the display window of the PDF viewer, e.g. Adobe Reader.

Name of the “view”

Syntax of the “view”

Description of the “view”

XYZ

XYZ;number1; number2;
number3

The specified page is displayed so that the x-y coordinate (number1;number2) of the page is at the top left of the window. Number3 is the zoom factor for the page (e.g. Number3=1 is a zoom of 100%, Number3=2 is a zoom of 200%, etc.). Especially number3=0 means that the current zoom factor remains unchanged.

Fit

Fit

The specified page will be enlarged so much that the page fills the window exactly. If this is not possible exactly, the page is enlarged so that the page is always completely visible in the window. One dimension of the page then fills the window exactly. The other dimension of the page is then smaller than the window and is centred within the window.

FitH

FitH;number1

The specified page is displayed so that the y-coordinate number1 of the page is displayed exactly at the top of the window. At the same time, the page is enlarged so that the width of the page fills the window exactly.

FitV

FitV; number1

The specified page is displayed so that the x-coordinate number1 of the page is displayed exactly on the left edge of the window. At the same time, the page is enlarged so that the height of the page fills the window exactly.

FitR

FitR; number1; number2;
number3; number4

The values (number1;number2;number3;number4) are the coordinates of a rectangle within the page (x-value-left;y-value-bottom;x-value-right;y-value-top). The page is displayed and enlarged so that this rectangle fills the window exactly. If this is not possible exactly, the page is enlarged so that the rectangle is always completely visible in the window. One dimension of the rectangle then fills the window exactly while the other dimension of the rectangle is smaller than the window and is centered within the window.

FitB

FitB

The specified page is enlarged so that the page's bounding box exactly fills the window. If this is not possible, the page is enlarged so that the page's bounding box is always completely visible in the window. One dimension of the bounding box then fills the window exactly while the other dimension of the bounding box rectangle is smaller than the window and is centered within the window.

FitBH

FitBH;number1

The specified page is displayed so that the y-coordinate number1 of the page is displayed exactly at the top of the window. At the same time, the page is enlarged so that the width of the page's bounding box fills the window exactly.

FitBV

FitBV;number1

The specified page is displayed so that the x-coordinate number1 of the page is displayed exactly at the left edge of the window. At the same time, the page is enlarged so that the height of the page's bounding box fills the window exactly.

 

Examples:

a.) {XYZ;100;200;3}
The page is displayed so that the page coordinate (x;y) = (100;200) is at the top left edge of the window. Zoom factor for the page is 300%.

b.) {XYZ;200;300;0}
The page is displayed so that the page coordinate (200;300) is at the top left of the window. Zoom factor for the page remains unchanged.

c.) {FitH;200}
The specified page is displayed so that the y-coordinate 200 of the page is exactly at the top of the window. At the same time, the page is enlarged so that the width of the page fills the window exactly.

d.) {FitV;100}
The specified page is displayed so that the x-coordinate 100 of the page is exactly at the left edge of the window. At the same time, the page is enlarged so that the page fills the height of the window exactly.

e.) {FitR;20;40;100;400}
The rectangle with the x-coordinates 20 and 100, and the y-coordinates 40 and 400 should fill the window. If this is not possible exactly, the page is enlarged so that the rectangle is always completely visible in the display window. One dimension of the rectangle then fills the window exactly while the other dimension of the rectangle is smaller than the window and is centered within the window.


Text

A string that specifies the name under which the bookmark is displayed in the bookmarks window of the viewer (e.g. from Adobe).

Important:

If in the name appear one of these characters      ;{}\      , this special character has to be marked with a backslash "\" symbol.

Example:
The bookmark name in the PDF viewer: “{Berlin;Hamburg}”
requires the following “text” in “OutlinesAdd”: “\{Berlin\;Hamburg\}”
The bookmark name in the PDF viewer: “Q\R; V\R; L\Z”
requires the following “text”: “Q\\R\; V\\R\; L\\Z”.


Subbookmarks

The entry for "subbookmarks" is optional. If it exists, it specifies one or more bookmarks that are sub-bookmarks to the specified bookmark..

A.) There are two possibilities of syntax indicating that a bookmark has no subbookmark.

a.) By removing the whole entry and the semicolon before it:

{Seitennummer;{Ansicht};Text}

b.) Or by leaving the curly brackets empty:     

{page number;{view};text;{}}

E.g.:       {1;{Fit};chapter 1}      und     {1;{Fit};chapter 1;{}}       are identical bookmarks without subbookmarks.

B.) If there are subbookmarks, they consist of one or more bookmarks. These are structured exactly like the other bookmarks. This way you can specify a whole chain of main, sub and sub-sub bookmarks.

Here are several examples for this "bookmark chaining". For convenience of the user, "{Fit}" is always used as "view". Of course, all other "views" described above can also be used in each individual bookmark. The colors are only for better comprehensibility: Different colors mean different individual bookmarks.

a.)      {1;{Fit};bookmark 1}

is an individual bookmark called "bookmark 1", which refers to page 1. This has no subbookmarks. You can also write this alternatively     

{1;{Fit};bookmark 1;{}}

b)       {1;{Fit};1. mail chapter 1};{4;{Fit};2. main chapter 2};{8;{Fit};3. main chapter 3}

are three (main) chapters. None of them has subbookmarks. The bookmark with the name “1. main chapter 1” (violet font) refers to page 1. The bookmark with the name “2. main chapter 2” (blue font) refers to page 4. And the bookmark named “3. main chapter 3” (green fontrefers to page 8.  

    c)      {1;{Fit};1. mail chapter 1;{{4;{Fit};1.1. main chapter 1};{7;{Fit};1.2. main chapter 2}}}

specifies a bookmark named "1. main chapter 1" (black font), which refers to page 1. This has 2 subbookmarks: One called "1.1. sub chapter 1 (violet font); which refers to page 4. And one with the name “1.2. sub chapter 2” (blue font) which refers to page .

    d)      {1;{Fit};1. main chapter 1;{{2;{Fit};1.1. sub chapter 1;{{3;{Fit};1.1.1. sub chapter 1;{{5;{Fit};1.1.1.1. sub sub chapter 1} }}}}}}

indicates a bookmark with the name "1. main chapter 1" (black font) that refers to page 1. This has a subbookmark named "1.1. subchapter 1” (violet font), which refers to page 2. This has a subbookmark with the name "1.1.1. sub subchapter 1” (blue font), which refers to page 3. This one has a subbookmark too called “1.1.1.1. sub sub subchapter 1” (green font), which refers to page 5.

The structure of these bookmarks would look as follows in the viewer (colors are only for clarification. The bookmarks in the PDF viewer would not have these colors):

1.         main chapter 1

1.1.      sub chapter 1

1.1.1. sub sub chapter 1

1.1.1.1. sub sub sub chapter 1

e)      {3;{Fit};1. main chapter 1;{{6;{Fit};1.1. sub chapter 1;{{9;{Fit};1.1.1. sub sub chapter 1};{11;{Fit};1.1.2. sub sub chapter 2;{{13;{Fit};1.1.2.1. sub sub sub chapter 1}}};{16;{Fit};1.1.3 sub sub chapter 3}}};{21;{Fit};1.2. sub chapter 2}}};{25;{Fit};2. main chapter 2;{}}

Die Struktur dieser Lesezeichen würde wie folgt aussehen:

The structure of these bookmarks would look as follows:

1. main chapter 1

1.1. sub chapter 1

1.1.1. sub sub chapter 1

1.1.2. sub sub chapter 2

1.1.2.1. sub sub sub chapter 1

1.1.3 sub sub chapter 3

1.2. sub chapter 2

2. main chapter 2

f)      {6;{Fit};1. main chapter 1;{{9;{Fit};1.1. sub chapter 1;{{12;{Fit};1.1.1. sub sub chapter 1;{{15;{Fit};1.1.1.1. sub sub sub chapter 1} }};{17;{Fit};1.1.2. sub sub chapter 2;{{21;{Fit};1.1.2.1. sub sub sub chapter 1};{23;{Fit};1.1.2.2. sub sub sub chapter 2}}} }};{25;{Fit};1.2. sub chapter 2}}};{28;{Fit};2. main chapter 2}

The structure of these bookmarks would look as follows:

1. main chapter 1

1.1. sub chapter 1

1.1.1. sub sub chapter 1

1.1.1.1. sub sub sub chapter 1

1.1.2. sub sub chapter 2

1.1.2.1. sub sub sub chapter 1

1.1.2.2. sub sub sub chapter 2

1.2. sub chapter 2

2. main chapter 2