Bookmarks

Here you will find examples to use bookmark.

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

Since

Version 1.4.1 R383, 28. June 2007

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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

Preconditions

#include "internal/types.h"

Since

Plugin Version 1.3.4

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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;
}

Since

Plugin Version 1.3.4

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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

Preconditions

#include "internal/types.h"

Since

Plugin Version 1.3.4

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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;
}

Since

Plugin Version 1.3.4

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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.

Since

Plugin Version 1.3.4

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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

Since

Plugin Version 1.3.4

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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

Since

Plugin Version 1.3.4

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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

Since

Plugin Version 1.3.4

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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

Since

Plugin Version 1.3.4

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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

Since

Plugin Version 1.3.4

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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.

Since

Plugin Version 1.3.4

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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

Since

Plugin Version 1.3.4

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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

Since

Plugin Version 1.3.4

Available

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

Since

Plugin Version 1.3.4

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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

Since

Plugin Version 1.3.4

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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

Since

Plugin Version 1.3.4

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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

Preconditions

#include "internal/text.h"

Since

v4.1.8 R29650, 22. Dec. 2021

Available

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

Preconditions

#include "internal/text.h"

Since

v4.1.8 R29650, 22. Dec. 2021

Available

comet_pdf

See Also

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

Since

Plugin Version 1.3.4

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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

16.10.2024, 11:40 Uhr

Since

Plugin Version 1.3.4

See Also

hyperlink

Alphabetic index HTML hierarchy of classes or Java