Bookmarks

Here you will find examples to use bookmark.

Version :
12.06.2024, 12:34 Uhr

Bookmarks

static int is_valid(ItemRef itemRef)

Does the reference point to an existing bookmark?

Name Type Default Description
Return int   1 : Yes, the ref points to an existing bookmark.

0 : No bookmark referenced. Do not use this reference as to be a bookmark
itemRef ItemRef - Any ItemRef or 0

Version 1.4.1 R383, 28. June 2007

priint:comet InDesign® Plug-Ins, comet_pdf

item::defined
comet.CBookmark.isValid

static int create(
  ItemRef createdItem,
  ItemRef docRef,
  char* destDoc,
  int pageNum,
  char* name,
  char* parentName,
  int pos = -1,
  float zoomPercent = 0.0,
  int destType = 0,
  float zoomRLeft = 0.0,
  float zoomRTop = 0.0,
  float zoomRRight = 0.0,
  float zoomRBottom = 0.0)

Create a new bookmark.

Name Type Default Description
Return int   0 or ErrorCode
createdItem ItemRef - Allocated reference to the new created bookmark

0 : Result not needed
otherwise : with item::alloc allocated reference
docRef ItemRef - Destination document

0 : front document
destDoc String or char* - Destination document for the bookmark. Ignored in the current version. For now, you can set bookmarks inside a document only
pageNum int - Destination page (1-based)
name String or char* - Name of bookmark showing in the bookmark panel
parentName String or char* "" Name of parent bookmark. If there are more than one bookmark this the given name, the last entry is used. Use add to define a unique parent.

"" : top level
pos int -1 Sibling position

-1 : Append
otherwise : 0-based index (see position)
⇨ After jumping to the bookmarks destination, InDesign® can change the zoom size of the document.
zoomPercent float 0.0 Zoom factor of destination page (1.0 is equal 100%)

0.0 : Do not change the zoom
destType int kBookmarkDestXYZ Position of destination page in the documents window. InDesign® gives the following (undocumented) alternatives:

kBookmarkDestXYZ
kBookmarkDestFit
kBookmarkDestFitH
kBookmarkDestFitV
kBookmarkDestFitR
kBookmarkDestFitB
kBookmarkDestFitBH
kBookmarkDestFitBV
⇨ Change the view rectangel at the destination - but be aware of side effects with zoomPercent and destType
zoomRLeft float 0.0 left margin of view rectangle
zoomRTop float 0.0 top margin of view rectangle
zoomRRight float 0.0 right margin of view rectangle
zoomRBottom float 0.0 bottom margin of view rectangle
#include "internal/types.h"

Plugin Version 1.3.4

priint:comet InDesign® Plug-Ins, comet_pdf

add
create2
add2
comet.CDocument.createBookmark

static int create2(
  ItemRef createdItem,
  ItemRef docRef,
  ItemRef hyperlinkRef,
  char* name,
  char* parentName,
  int pos = -1)

Create a bookmark to an existing anchor created with hyperlink::create.

Name Type Default Description
Return int   0 or ErrorCode
createdItem ItemRef - Allocated reference to the new created bookmark

0 : result not needed
otherwise : with item::alloc allocated reference
docRef ItemRef - Docuemt to create the bookmark

0 : front document
hyperlinkRef ItemRef - bookmark destination (hyperlink::destination to an anchor created using hyperlink::create)
name String or char* - Name of bookmark
parentName String or char* "" Name of parent bookmark. If there are more than one bookmarks with this name, the last entry is used. Use add to define a unique parent.

"" : top level
pos int -1 Sibling position

-1 : Append
otherwise : 0-based index (see position)

The scripts creates a hyperlink to page 5 at the textposition 11-18 in the current text model. Current text is using as the hyperlinks name. After it a bookmark this the same name and destination is created at the top level of the bookmarks.

int main ()
{
    ItemRef		hy		= item::alloc ();
    ItemRef		dest	= item::alloc ();
    ItemRef		bk		= item::alloc ();
hyperlink::create (hy, 0, "", 5, "", 11, 18); bookmark::create2 (   bk,   0,   hyperlink::destination (dest, hy),   hyperlink::name (hy),   "");
return 0; }

Plugin Version 1.3.4

priint:comet InDesign® Plug-Ins, comet_pdf

create
add
add2

static int add(
  ItemRef createdItem,
  ItemRef docRef,
  char* destDoc,
  int pageNum,
  char* name,
  ItemRef parentRef,
  int pos = -1,
  float zoomPercent = 0.0,
  int destType = 0,
  float zoomRLeft = 0.0,
  float zoomRTop = 0.0,
  float zoomRRight = 0.0,
  float zoomRBottom = 0.0)

Create a new bookmark as a sibling of an existing bookmark. The function is identical to create - the only difference being, that the parent is given by a reference and not by name.

Name Type Default Description
Return int   0 or ErrorCode
createdItem ItemRef - Allocated reference to the newly created bookmark

0 : Result not needed
otherwise : reference allocated with item::alloc
docRef ItemRef - Destination document

0 : front document
destDoc String or char* - Destination document for the bookmark. Ignored in the current version. For now, you can set bookmarks inside a document only
pageNum int - Destination page (1-based)
name String or char* - Name of bookmark showing in the bookmark panel
parentRef ItemRef - Reference to parent bookmark

0 : top level
pos int -1 Sibling position

-1 : Append
otherwise : 0-based index (see position)
⇨ After jumping to the bookmarks destination, InDesign® can change the zoom size of the document.
zoomPercent float 0.0 Zoom factor of destination page (1.0 is equal 100%)

0.0 : Do not change the zoom
destType int kBookmarkDestXYZ Position of destination page in the documents window. InDesign® gives the following (undocumented) alternatives:

kBookmarkDestXYZ
kBookmarkDestFit
kBookmarkDestFitH
kBookmarkDestFitV
kBookmarkDestFitR
kBookmarkDestFitB
kBookmarkDestFitBH
kBookmarkDestFitBV
⇨ Change the view rectangel at the destination - but be aware of side effects with zoomPercent and destType
zoomRLeft float 0.0 left margin of view rectangle
zoomRTop float 0.0 top margin of view rectangle
zoomRRight float 0.0 right margin of view rectangle
zoomRBottom float 0.0 bottom margin of view rectangle
#include "internal/types.h"

Plugin Version 1.3.4

priint:comet InDesign® Plug-Ins, comet_pdf

add
create2
add2
create
create2
add2
comet.CBookmark.createBookmark

static int add2(
  ItemRef createdItem,
  ItemRef docRef,
  ItemRef hyperlinkRef,
  char* name,
  ItemRef parentRef,
  int pos = -1)

Create a bookmark to an existing anchor created with hyperlink::create. Parent bookmark is given by a reference.

Name Type Default Description
Return int   0 or ErrorCode
createdItem ItemRef - Allocated reference to the newly created bookmark

0 : result not needed
otherwise : with item::alloc allocated reference
docRef ItemRef - Document to create the bookmark in

0 : front document
hyperlinkRef ItemRef - bookmark destination (hyperlink::destination to an anchor created using hyperlink::create)
name String or char* - Name of bookmark
parentRef ItemRef 0 Reference to parent bookmark

"" : top level
pos int -1 Sibling position

-1 : Append
otherwise : 0-based index (see position)

The scripts creates a hyperlink to page 5 at the textposition 11-18 in the current text model. Current text is using as the hyperlinks name. After it a bookmark this the same name and destination is created at the top level of the bookmarks.

int main ()
{
    ItemRef		hy		= item::alloc ();
    ItemRef		dest	= item::alloc ();
    ItemRef		bk		= item::alloc ();
hyperlink::create (hy, 0, "", 5, "", 11, 18); bookmark::create2 (   bk,   0,   hyperlink::destination (dest, hy),   hyperlink::name (hy),   "");
return 0; }

Plugin Version 1.3.4

priint:comet InDesign® Plug-Ins, comet_pdf

create
add
add2

static int find(
  ItemRef foundRef,
  ItemRef docRef,
  char* name)

Find a bookmark by its name

Name Type Default Description
Return int   0 or ErrorCode
foundRef ItemRef - Allocated reference for the result
0 : ignore. In this case, the fuction is used to check whether a given bookmark exists or not.
docRef ItemRef - Document to search
0 : front document
name String or char* - Name of bookmark to search for. If the name is not unique, the last entry is returned.

Plugin Version 1.3.4

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CDocument.getBookmarks

static int level(ItemRef bookMarkRef)

Get the nesting level of a bookmark

Name Type Default Description
Return int   Nesting level (0-based) or 0 if not found.
bookMarkRef ItemRef - Reference to an existing bookmark

Plugin Version 1.3.4

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CBookmark.getDepth

static char* name(ItemRef bookMarkRef)

Get the name of a bookmark

Name Type Default Description
Return char*   Name of bookmark or "" in case of some errors.

The return value is read only, do NOT CHANGE. The result will be overridden on following calls to the function. See here to learn more about functions returning r/o char* values.

bookMarkRef ItemRef - Reference to an existing bookmark

Plugin Version 1.3.4

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CBookmark.getName

static int parent(ItemRef foundRef, ItemRef bookMarkRef)

Query out the bookmarks parent

Name Type Default Description
Return int   0 or ErrorCode
foundRef ItemRef - Allocated reference for the result
bookMarkRef ItemRef - Reference to an existing bookmark

Plugin Version 1.3.4

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CBookmark.getParent

static int position(ItemRef foundRef)

Sibling position of a bookmark

Name Type Default Description
Return int   0-based position or -1 in case of some errors
bookMarkRef ItemRef - Reference to an existing bookmark

Plugin Version 1.3.4

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CBookmark.getIndex

static int childs(ItemRef bookMarkRef)

Count the number of children

Name Type Default Description
Return int   number of children or 0 in case of some errors
bookMarkRef ItemRef - Reference to an existing bookmark

Plugin Version 1.3.4

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CBookmark.getChildren

static int nthchild(
  ItemRef foundRef,
  ItemRef bookMarkRef,
  int index)

Get the n-th sibling of a bookmark

Name Type Default Description
Return int   0 or ErrorCode
foundRef ItemRef - Allocated reference for the result
bookMarkRef ItemRef - Reference to an existing bookmark
index int - 0-based index of the sibling. If the parent has no childs, the empty reference is returned. If index is < 0, the first child is returned. If index is >= childs, the last child is returned.

Plugin Version 1.3.4

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CBookmark.getChildren

static int child(
  ItemRef foundRef,
  ItemRef bookMarkRef,
  char* name,
  int recursive = 0)

Find a child by its name

Name Type Default Description
Return int   0 or ErrorCode
foundRef ItemRef - Allocated reference for the result
bookMarkRef ItemRef - Reference to an existing bookmark
name String or char* - Name to search for
recursive int 0 0 : search only direct children, the first matching entry is returned

otherwise : recursive search, the last matching entry is returned

Plugin Version 1.3.4

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CBookmark.getChildren

static int goto_(ItemRef bookMarkRef)

Jump to the bookmarks destination

Name Type Default Description
Return int   0 or ErrorCode
bookMarkRef ItemRef - Reference to an existing bookmark

Plugin Version 1.3.4

priint:comet InDesign® Plug-Ins, comet_pdf

static int change_pos(ItemRef bookMarkRef, int pos)

Change the bookmarks position inside the parent level. You can change the position only inside the parent level. To change the bookmarks parent, use change_parent please.

Name Type Default Description
Return int   0 or ErrorCode
bookMarkRef ItemRef - Reference to an existing bookmark
pos int - New position (0-based), if position is >= childs move the entry to the last position

Plugin Version 1.3.4

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CBookmark.setIndex

static int change_name(ItemRef bookMarkRef, char* name)

Change the bookmarks name

Name Type Default Description
Return int   0 or ErrorCode
bookMarkRef ItemRef - Reference to an existing bookmark
name String or char* - New name

Plugin Version 1.3.4

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CBookmark.setName

static int change_parent(
  ItemRef bookMarkRef,
  ItemRef parentRef = 0,
  int pos = -1)

Change the bookmarks parent

Name Type Default Description
Return int   0 or ErrorCode
bookMarkRef ItemRef - Reference to an existing bookmark
parentRef ItemRef - New parent
0 : top level
pos int -1 Position inside the parent
-1 : Append

Plugin Version 1.3.4

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CBookmark.setParent

static int change_fontstyle(ItemRef bookMarkRef, int fstyle = 0)

Change the font style of the bookmark.

InDesign does not support font styles in bookmarks! The function is therefore implemented only for comet_pdf. In other environments the function returns the error code -1199.

Name Type Default Description
Return int   0 or ErrorCode
bookMarkRef ItemRef - Valid book mark reference
fstyle int 0 Font style of bookmark

normal : normal
bold : bold
italic : italic
bold+italic : bold and italic
#include "internal/text.h"

v4.1.8 R29650, 22. Dec. 2021

comet_pdf

static int change_color(ItemRef bookMarkRef, ItemRef colorRef = 0)

Change the font color of the bookmark.

InDesign does not support colored bookmarks! The function is implemented therfore only for comet_pdf. In other environments the function returns the error code -1199.

Name Type Default Description
Return int   0 or ErrorCode
bookMarkRef ItemRef - Valid book mark reference
colorRef ItemRef 0 Valid color reference

0 : Black
Otherwise : Valid RGB color
#include "internal/text.h"

v4.1.8 R29650, 22. Dec. 2021

comet_pdf

color
comet.CBookmark.setColor

static int remove(ItemRef bookMarkRef)

Remove a bookmark from the document. The script variable bookMarkRef is set to the empty reference but not released.

Name Type Default Description
Return int   0 or ErrorCode
bookMarkRef ItemRef - Reference to an existing bookmark

Plugin Version 1.3.4

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CBookmark.remove

The example demonstrates the use of the bookmark functions. After executing the script, the top entry of bookmark panel should look like the figure :

int main ()
{
    ItemRef		bm	= item::alloc ();
    ItemRef		bm1	= item::alloc ();
    ItemRef		bm2	= item::alloc ();
    ItemRef		bm3	= item::alloc ();
wlog ("", "childs doc : %d\n", bookmark::childs (0));
bookmark::create (bm, 0, "", 1, "Inhaltsverzeichnis", "", 1); wlog ("", "name : %s\n", bookmark::name (bm)); bookmark::change_pos (bm, 0);
bookmark::add (bm1, 0, "", 1, "Leszeichen 1", bm); bookmark::add (bm2, 0, "", 2, "Leszeichen 2", bm); bookmark::add (bm3, 0, "", 3, "Leszeichen 3", bm);
bookmark::goto_ (bm3); bookmark::remove (bm3); wlog ("", "childs inhalt : %d\n", bookmark::childs (bm));
bookmark::change_parent (bm2, bm1);
bookmark::change_name (bm, "[A] Inhaltsverzeichnis"); wlog ("", "neuer name : %s\n", bookmark::name (bm));
return 0; }

The scripts creates a hyperlink to page 5 at the textposition 11-18 in the current text model. Current text is using as the hyperlinks name. After it a bookmark this the same name and destination is created at the top level of the bookmarks.

int main ()
{
    ItemRef		hy		= item::alloc ();
    ItemRef		dest	= item::alloc ();
    ItemRef		bk		= item::alloc ();
hyperlink::create (hy, 0, "", 5, "", 11, 18); bookmark::create2 (   bk,   0,   hyperlink::destination (dest, hy),   hyperlink::name (hy),   "");
return 0; }

Here is a complete example of creating bookmarks in a PDF created by comet_pdf. The script assumes the existence of frames with specified UID. You can find a corresponding test file here. The following terminal command can be used to run the script:

    /.comet_pdf -i \$DESKTOP/bm.w2ml -e \$DESKTOP\bookmarks.cpp -L

Here is a screenshot of the result:

#include "internal/types.h"
#include "internal/text.h"
int main () { ItemRef head = item::alloc (); ItemRef bm = item::alloc (); ItemRef bb = item::alloc (); ItemRef hy = item::alloc (); ItemRef fr = item::alloc (); ItemRef colid = item::alloc (); IDTypeList anchors = idtypelist::alloc (-1); IDType anchor; Table T = table::alloc (); int i, start, len; ItemList hyperlinks;
color::define_rgb ("", 255, 128, 0, 0, colid);
// Create some book marks // bookmark::create (head, 0, 0, 1, "pg. 1"); // jump to pg 1 bookmark::change_fontstyle (head, bold+italic); bookmark::change_color (head, colid);
bookmark::create (bm, 0, 0, 2, "pg. 2", "pg. 1"); // jump to pg 2 bookmark::change_fontstyle (bm, bold); bookmark::create (bm, 0, 0, 3, "pg. 3", "pg. 1"); // jump to pg 3
bookmark::create (bm, 0, 0, 4, "Seite 4", "pg. 1", -1, 0.0, kBookmarkDestXYZ, 0.0, 263.0, 1.0, 300.0); bookmark::create (bm, 0, 0, 2, "Seite 2", "pg. 1"); bookmark::create (bm, 0, 0, 3, "Seite 3", "pg. 1"); bookmark::create (bm, 0, 0, 4, "Seite 4", "pg. 1");
bookmark::create (bm, 0, 0, 4, "pg. 4");
printf ("UID_AAA of 'a4' : %d\n", item::getint (bm)); bookmark::add (bm, 0, 0, 1, "Sivu 1", head); bookmark::change_fontstyle (bm, italic); bookmark::add (bm, 0, 0, 2, "Sivu 2", head); bookmark::add (bm, 0, 0, 3, "Sivu 3", head);
// Check bookmark functions //
// name bookmark::find (bm, 0, "pg. 4"); printf ("UID_BBB of '%s' : %d\n", bookmark::name (bm), item::getint (bm));
// parent bookmark::find (bm, 0, "Seite 2"); bookmark::parent (bb, bm); printf ("Parent of 'b2' is '%s' with UID %d\n", bookmark::name (bb), item::getint (bb)); printf ("'b2' has UID %d\n", item::getint (bm));
// childs bookmark::find (bm, 0, "pg. 1"); printf ("'a2' has %d children\n", bookmark::childs (bm));
// nthchild bookmark::nthchild (bb, bm, 2); printf ("3rd child of 'a2' is '%s\n", bookmark::name (bb));
// child bookmark::find (bm, 0, "pg. 1"); bookmark::child (bb, bm, "Seite 2", 0); printf ("'a1' has direct child 'b2' ? %d\n", item::getint (bb));
bookmark::child (bb, bm, "Seite 2", 1); printf ("'a1' has child 'b2' ? %d\n", item::getint (bb));
// is_valid printf ("%d is a valid book mark ? %d\n", item::getint (bb), bookmark::is_valid (bb)); item::define (bb, 0, 123, 0); printf ("%d is a valid book mark ? %d\n", item::getint (bb), bookmark::is_valid (bb));
// change_pos bookmark::find (bm, 0, "Seite 4"); bookmark::change_pos (bm, 3);
bookmark::find (bm, 0, "Seite 4"); bookmark::change_pos (bm, 0);
// change_name bookmark::find (bm, 0, "Seite 4"); bookmark::change_name (bm, "New name of 'Seite 4'");
// change_parent bookmark::find (bm, 0, "Seite 4"); bookmark::find (bb, 0, "Sivu 1"); bookmark::change_parent (bm, bb, 1);
// remove bookmark::find (bm, 0, "Sivu 1"); //bookmark::remove (bm);
// Create named destinations to some text and add bookmarks // item::define (fr, 0, 330); hyperlink::add_nameddest (hy, 0, fr, 1089, 0); printf ("AA-> hyperlink dest of uid %d created at text position 1089\n", item::getint (hy)); bookmark::create2 (bm, 0, hy, "occusamus", 0, -1);
hyperlink::add_nameddest (hy, 0, fr, 1697, 0); printf ("BB-> hyperlink dest of uid %d created at text position 1690\n", item::getint (hy)); bookmark::create2 (bm, 0, hy, "oditasim", 0, -1);
table::get (T, fr, 0); table::cell::get_textpos (T, 1, 2, &start, &len); hyperlink::add_nameddest (hy, 0, fr, start, 7); // inside a table printf ("CC-> hyperlink dest of uid %d created at text position %d\n", item::getint (hy), start); bookmark::create2 (bm, 0, hy, "AAAAA", 0, -1);
// Create named destinations to some frames and add bookmarks // item::define (fr, 0, 327); hyperlink::add_nameddest (hy, 0, fr, -1, 0); // frame printf ("hyperlink dest of uid %d created\n", item::getint (hy)); bookmark::create2 (bm, 0, hy, "Blue Frame", 0, -1);
item::define (fr, 0, 369); hyperlink::add_nameddest (hy, 0, fr, -1, 0); // frame bookmark::add2 (bb, 0, hy, "Yellow Frame", bm);
// Get anchors of frames // item::define (fr, 0, 327); if (hyperlink::get_nth (fr, -1, hy) == 0) { printf ("Frame %d has an named dest : '%s'\n", item::getint (fr), hyperlink::name (hy)); } else { printf ("Frame %d has no named anchor\n", item::getint (fr)); }
item::define (fr, 0, 330); if (hyperlink::get_nth (fr, -1, hy) == 0) { printf ("Frame %d has an named dest : '%s'\n", item::getint (fr), hyperlink::name (hy)); } else { printf ("Frame %d has no named anchor\n", item::getint (fr)); }
// Get hyperlinks of text // item::define (fr, 0, 330);
printf ("Frame %d has %d hyperlinks\n", item::getint (fr), hyperlink::count (fr));
hyperlinks = itemlist::hyperlinks (fr); printf ("Frame %d has %d hyperlinks\n", item::getint (fr), itemlist::length (hyperlinks)); for (i = 0; i < itemlist::length (hyperlinks); i++) { itemlist::get (hyperlinks, hy, i); start = hyperlink::get_pos (hy, &len, fr); printf (" %d : %d %d (%s) Type = %d\n", i+1, start, len, hyperlink::name (hy), hyperlink::type (hy)); }
return 0; }

Author
Paul Seidel
Version
12.06.2024, 12:34 Uhr
Since
Plugin Version 1.3.4
See Also
hyperlink

Alphabetic index HTML hierarchy of classes or Java