Deal with InDesign^® books

Here you will find examples to use book.

Deal with InDesign^® books

static int create(char* fullpath)

Create a new empty book. The book is NOT opened automatically.

Name	Type	Default	Description
Return	int		0 or ErrorCode
fullpath	String or char*	-	Complete path to the resulting book. The file name must should end with an extender (.indb). The path will be created if nesseccary.

Since

Plugin Version 1.4.2 R 505, 14. Nov. 2007

Verfügbarkeit

priint:comet InDesign^® Plug-Ins

See Also

open
save
close
comet.book.create

static int open(char* fullpath, ItemRef bookRef = 0)

Open a book.

Name	Type	Default	Description
Return	int		0 or ErrorCode
fullpath	String or char*	-	Complete path to the book.
bookRef	ItemRef	0	On success a valid reference to the opened booked. You should create this ref before the call using item::alloc.

Since

Plugin Version 1.4.2 R 505, 14. Nov. 2007

Available

priint:comet InDesign^® Plug-Ins

See Also

create
open
close
comet.book.open

static int count()

Determine the number of currently open books.

Name	Type	Default	Description
Return	int		Number of currently open books 0 : no books open or errors

int main ()
{
    int 		B	= book::count ();
    int 		b;
    ItemRef		bref= item::alloc ();

    for (b = 0; b < B; b++)
    {
        book::get_nth (b, bref);
        wlog ("", "# %d. book	: '%s'\n", b, book::get_path (bref));
    }

    book::get_current (bref);
    wlog ("", "Current book	: '%s'\n", book::get_path (bref));

    book::get_by_path ("$DESKTOP/Buch 3.indb", bref);
    wlog ("", "Thrd book	: '%s'\n", book::get_path (bref));

    book::set_current (bref);
    book::get_current (bref);
    wlog ("", "Current book	(2): '%s'\n", book::get_path (bref));

    return 0;
}

Since

v4.1.6 R25445, 19. Jul 2019

Available

priint:comet InDesign^® Plug-Ins

See Also

get_nth
get_path
get_by_path
comet.book.getOpen

static int get_nth(int nth, ItemRef out_bookRef)

Get the nth open book. The result is a reference to an open book. The path of the book can be determined with get_path.

Name	Type	Default	Description
Return	int		0 or ErrorCode
nth	int	-	0-based index of book
out_bookRef	ItemRef	0	After successful execution, the variable contains a reference to the nth book. The path of the book can be determined with get_path.

You can find an example under count.

see count

Since

v4.1.6 R25445, 19. Jul 2019

Available

priint:comet InDesign^® Plug-Ins

See Also

count
get_path
get_by_path
comet.book.getOpen

static char* get_path(ItemRef bookRef)

Determine the complete path of a book.

Name	Type	Default	Description
Return	char*		Complete path of the book incl. its name 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.
bookRef	ItemRef	-	Valid reference to an open book.

You can find an example under count.

siehe count

Since

v4.1.6 R25445, 19. Jul 2019

Available

priint:comet InDesign^® Plug-Ins

See Also

count
get_nth
get_by_path
open
create
comet.CBook.getPath

static int get_by_path(char* path, ItemRef out_bookRef)

Determine from the file path of an InDesign^® book the current reference in the program. To obtain a valid reference, the book file exist and the book must be opened in InDesign^®!

Name	Type	Default	Description
Return	int		0 or ErrorCode To obtain a valid reference, the book file exist and the book must be opened in InDesign®!
path	String oder char*	-	Full path of an InDesign® book file
bookRef	ItemRef	-	After successful execution, the variable contains a reference to given book.

Ein Beispiel finden Sie unter count.

siehe count        

Since

v4.1.6 R25445, 19. Jul 2019

Available

priint:comet InDesign^® Plug-Ins

See Also

count
get_nth
open
create
comet.book.getByPath

static int get_current(ItemRef out_bookRef)

Get the currently 'active' book.

Please note: The active book is the book you last worked on. The active book may change by script calls for other books!

Here is an article from InDesign Secrets:

A note on "activeBook"

One more note, in case you’re going to be scripting book panels: Before you add your own custom options to the Book panel, you have to make sure it works as intended in a standalone script. Now there is something weird going on when using 'activeBook'. Other than, say, 'activeDocument', 'activeBook' does not always get right what book document is the active one! The reason for this is that you can have several book panels open at a time, scattered about your workspace. Which one is then "active"? So when experimenting with this, you’d better make sure you only have one single book open. I was kind of weary of this issue when testing my open/close script, but it seems that if you call a script from within the book panel itself, 'the' active book is indeed the one you called the menu from, so the problem resolved itself.

Name	Type	Default	Description
Return	int		0 or ErrorCode
out_bookRef	ItemRef	0	After successful execution, the variable contains a reference to 'acive' book. The path of the book can be determined with get_path.

You can find an example under count.

see count

Since

v4.1.6 R25445, 19. Jul 2019

Available

priint:comet InDesign^® Plug-Ins

See Also

count
get_path
get_by_path
comet.book.getCurrent

static int set_current(ItemRef bookRef)

Set the currently 'active' book.

Please note: The active book is the book you last worked on. The active book may change by script calls for other books!

Here is an article from InDesign Secrets:

A note on "activeBook"

One more note, in case you’re going to be scripting book panels: Before you add your own custom options to the Book panel, you have to make sure it works as intended in a standalone script. Now there is something weird going on when using 'activeBook'. Other than, say, 'activeDocument', 'activeBook' does not always get right what book document is the active one! The reason for this is that you can have several book panels open at a time, scattered about your workspace. Which one is then "active"? So when experimenting with this, you’d better make sure you only have one single book open. I was kind of weary of this issue when testing my open/close script, but it seems that if you call a script from within the book panel itself, 'the' active book is indeed the one you called the menu from, so the problem resolved itself.

Name	Type	Default	Description
Return	int		0 or ErrorCode
bookRef	ItemRef	0	New 'active' book

You can find an example under count.

see count

Since

v4.1.6 R25445, 19. Jul 2019

Available

priint:comet InDesign^® Plug-Ins

See Also

count
get_path
get_by_path
comet.CBook.setCurrent

static int is_valid(ItemRef bookRef)

Does a given reference point to an open book?

Name	Type	Default	Description
Return	int		1 : Yes 0 : Empty reference or reference does not point to an opened book
bookRef	ItemRef	-	Any reference

Since

Plugin Version 1.4.2 R 505, 14. Nov. 2007

Available

priint:comet InDesign^® Plug-Ins

See Also

open
comet.CBook.isValid

static int save(ItemRef bookRef)

Save a book.

Name	Type	Default	Description
Return	int		0 or ErrorCode
bookRef	ItemRef	-	Valid reference to a book opened before

Since

Plugin Version 1.4.2 R 505, 14. Nov. 2007

Available

priint:comet InDesign^® Plug-Ins

See Also

create
open
close
comet.CBook.save

static int close(ItemRef bookRef, int doSave = 1)

Close a book.

Name	Type	Default	Description
Return	int		0 or ErrorCode
bookRef	ItemRef	-	Valid reference to a book opened before
doSave	int	1	Save book before closing 0 : Do not save changes otherwise : save changes

Since

Plugin Version 1.4.2 R 505, 14. Nov. 2007

Available

priint:comet InDesign^® Plug-Ins

See Also

create
open
save
comet.CBook.close

static int insert(
  ItemRef bookRef,
  char* docPath,
  int location = -1,
  int updateCrossrefs = 0,
  int showProgress = 0,
  int repaginate = 1)

Insert a document to a opened book. If the document is already part of the book, the call does nothing. Optionally you can update all cross reference placeholders of the given book.

Name	Type	Default	Description
Return	int		0 or ErrorCode
bookRef	ItemRef	-	Valid reference to a book opened before
docPath	String or char*	-	Complete path to an existing InDesign® document
location	int	-1	0-based insertion point -1 : append
updateCrossrefs	int	0	Update cross reference placeholders? 0 : No 1 : Yes
showProgress	int	0	Show progress while updating cross reference placeholders? 0 : No 1 : Yes
repaginate	int	1	Repaginate pages (since 4.1 R22155) 0 : No 1 : Yes

Since

Plugin Version 1.4.2 R 505, 14. Nov. 2007
Parameter updateCrossrefs and showProgress since Vesion 2.1 R 668, 10. April 2008

Available

priint:comet InDesign^® Plug-Ins

See Also

open
comet.CBook.insertDocument

static int moveto(
  ItemRef bookRef,
  char* docPath,
  int pos,
  int updateCrossrefs = 0,
  int showProgress = 0)

Move a document to an new position inside the book. Optionally you can update all cross reference placeholders of the given book.

Name	Type	Default	Description
Return	int		0 or ErrorCode
bookRef	ItemRef	-	Valid reference to a book opened before
docPath	String or char*	-	Complete path to an InDesign® document
pos	int	-	New position inside the book (0-based) -1 : to the end of the book
updateCrossrefs	int	0	Update cross reference placeholders? 0 : No 1 : Yes
showProgress	int	0	Show progress while updating cross reference placeholders? 0 : No 1 : Yes

Since

Plugin Version 1.4.2 R 505, 14. Nov. 2007
Parameter updateCrossrefs and showProgress since Vesion 2.1 R 668, 10. April 2008

Available

priint:comet InDesign^® Plug-Ins

See Also

open
comet.CBook.setDocumentPosition

static int remove(
  ItemRef bookRef,
  char* docPath,
  int updateCrossrefs = 0,
  int showProgress = 0)

Removes a document from an opened book. if the document isn't a part of the book, the call does nothing. Optionally you can update all cross reference placeholders of the given book.

Name	Type	Default	Description
Return	int		0 or ErrorCode
bookRef	ItemRef	-	Valid reference to a book opened before
docPath	String or char*	-	Complete path to an InDesign® document
updateCrossrefs	int	0	Update cross reference placeholders? 0 : No 1 : Yes
showProgress	int	0	Show progress while updating cross reference placeholders? 0 : No 1 : Yes

Since

Plugin Version 1.4.2 R 505, 14. Nov. 2007
Parameter updateCrossrefs and showProgress since Vesion 2.1 R 668, 10. April 2008

Available

priint:comet InDesign^® Plug-Ins

See Also

open
comet.CBook.removeDocument

static int repaginate(
  ItemRef bookRef,
  int updateCrossrefs = 0,
  int showProgress = 0)

Repaginate an open book. Optionally you can update all cross reference placeholders of the given book.

Name	Type	Default	Description
Return	int		0 or ErrorCode
bookRef	ItemRef	-	Reference to an opened book
updateCrossrefs	int	0	Update cross reference placeholders? 0 : No 1 : Yes
showProgress	int	0	Show progress while updating cross reference placeholders? 0 : No 1 : Yes

Since

Plugin Version 1.4.2 R 505, 14. Nov. 2007
Parameter updateCrossrefs and showProgress since Vesion 2.1 R 668, 10. April 2008

Available

priint:comet InDesign^® Plug-Ins

See Also

insert
moveto
remove
comet.CBook.repaginate

static int position(ItemRef bookRef, char* docPath)

Find the location of a document inside a book.

Name	Type	Default	Description
Return	int		-1 : Document not found inside the book otherwise : 0-based doc position
bookRef	ItemRef	-	Valid reference to a book opened before
docPath	String or char*	-	Complete path to an InDesign® document

Since

Plugin Version 1.4.2 R 505, 14. Nov. 2007

Available

priint:comet InDesign^® Plug-Ins

See Also

open
comet.CBook.getDocumentPosition

static int set_master(ItemRef bookRef, char* docPath)

Set the Style Source of the book.

Name	Type	Default	Description
Return	int		-1 : Document not found inside the book otherwise : 0-based doc position
bookRef	ItemRef	-	Valid reference to a book opened before
docPath	String or char*	-	Complete path to an InDesign® document inside the book

Since

Plugin Version 1.4.2 R 505, 14. Nov. 2007

Available

priint:comet InDesign^® Plug-Ins

See Also

get_master
comet.CBook.setMasterDocument

static char* get_master(ItemRef bookRef)

Get the Style Source of the book.

Name	Type	Default	Description
Return	char*		Complete path to the document use to be the books style source document. "" : In case of an error 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.
bookRef	ItemRef	-	Valid reference to a book opened before

Since

Plugin Version 1.4.2 R 505, 14. Nov. 2007

Available

priint:comet InDesign^® Plug-Ins

See Also

set_master
comet.CBook.getMasterDocument

static int count_docs(ItemRef bookRef)

Count the documents of an opened book.

Name	Type	Default	Description
Return	int		Number of documents inside the book.
bookRef	ItemRef	-	Valid reference to a book opened before

Since

Plugin Version 1.4.2 R 505, 14. Nov. 2007

Available

priint:comet InDesign^® Plug-Ins

See Also

nth_doc
comet.CBook.getDocuments

static char* nth_doc(ItemRef bookRef, int n)

Name	Type	Default	Description
Return	char*		Complete path to the n-th document in the book. The result will be overridden on following calls to the function. "" : In case of an error
bookRef	ItemRef	-	Valid reference to a book opened before
n	i	-	0-based index in the book

Since

Plugin Version 1.4.2 R 505, 14. Nov. 2007

Available

priint:comet InDesign^® Plug-Ins

See Also

count_docs
comet.CBook.getDocuments

static int all_documents_do(
  char* bookPath,
  int actionID,
  int saveOnClose = 0)

Editing of all documents in a book. The documents are opened, edited and closed again in the order specified in the book. Previously opened documents remain open.

The function solves the problem that InDesign^® does not really close documents until the next idle time. This behaviour means that books with many documents can quickly lead to memory overflow and InDesign^® crashing when they are processed in a single script. all_documents_do solves the problem by processing the individual documents in separate idle time sequences. Between these steps, InDesign^® is given enough time to 'really' close closed documents.

Name	Type	Default	Description
Return	int		0 or Error Code
bookPath	String oder char*	-	Complete path of the book to be edited
actionID	int	-	ID from actions of the script for editing the individual documents. The documents are open at execution time and are always in the foreground. Global variables (read only!) char* gMyBook : Path (parameter bookPath) of book int gMyChapter : 0-based index of the document in the book Return values 0 : Okay Otherwise : Error and cancellation of the processing of further documents
saveOnClose	int	0	Should the individual documents be saved after processing? 0 : No, close documents without saving 1 : Yes, save changes to the documents

Use the following line to edit all documents of a book. The documents themselves are edited by action 170.

book::all_documents_do ("/Users/paul/Desktop/ID_19.0/Book 1.indb", 170, 1);

Action 170 creates an orange frame in the first document. For demo purposes, after the third document you are asked whether editing should be continued.

#include "internal/types.h"

int main ()
{
    ItemList		frames;
    ItemRef 		fr	= item::alloc ();
    char 			pp	[5000];
    int 			res	= 0;

    wlog ("", "BOOK %s, CHAPTER %d\n", gMyBook, gMyChapter);

    if (gMyChapter == 0)
    {
        frame::create (fr, kRectangle, 0.0, 0.0, 300.0, 50.0, 1);
        frame::color_rgb (fr, 255, 128, 0);
    }

    frames = itemlist::allframes ();
    wlog("", "### %d frame(s) found in doc '%s'\n",
     		itemlist::length (frames),
     		document::path (pp));

    itemlist::release (frames);
    item::release (fr);

    // For demonstration purposes only
    //
    if (gMyChapter == 2)
    {
        res = alert ("Proceed", "Cancel", 0, 1, 2,
         		"%d documents proceeded. Should I proceed with the next documents?",
         		gMyChapter+1);
        if (res == 1) 	res = 0;  // Proceed
    }

    return res;
}

Since

v4.3 R34900, 11. Jun 2024

Verfügbarkeit

priint:comet InDesign^® Plug-Ins

static int export_(
  ItemRef bookRef,
  char* pdfPath = 0,
  char* styleName = 0)

Export a book as a PDF document.

Name	Type	Default	Description
Return	int		0 or ErrorCode
bookRef	ItemRef	-	Valid reference to an open book
pdfPath	String or char*	0	Path for the export file 0 : Use path and name of book file with the extension pdf. otherwise : Complete path and file name. The path is created automatically.
styleName	String or char*	0	Export style name : 0 : Current default style otherwise : Name of an existing PDF export style Style names must be case seinsitive.

Since

Plugin Version 1.4.2 R 505, 14. Nov. 2007

Available

priint:comet InDesign^® Plug-Ins

See Also

open
comet.CBook.exportPDF

Demostrating some book function calls and logs the result to the global logfile. You must have the three documents book.indd, book2.indd and book3.indd on your desktop.

int main ()
{
    ItemRef		bookRef	= item::alloc ();
    int       	rt;
    char		bookPath[256];
    char		doc1[256];
    char		doc2[256];
    char		doc3[256];
    char*		masterDoc;

    strcpy (bookPath, 	"$DESKTOP/book.indb");
    strcpy (doc1, 		"$DESKTOP/book.indd");
    strcpy (doc2, 		"$DESKTOP/book2.indd");
    strcpy (doc3, 		"$DESKTOP/book3.indd");

    rt = book::create (bookPath);
    wlog ("", "Create book returned %d.\n", rt);

    rt = book::open (bookPath, bookRef);
    wlog ("", "Open book returned %d.\n", rt);

    rt = book::is_valid (bookRef);
    wlog ("", "bookRef valid? %d\n", rt);
    if (!rt)	return 0;

    rt = book::insert (bookRef, doc1, 0);
    wlog ("", "Insert doc1 in book returned %d.\n", rt);

    rt = book::insert (bookRef, doc2, 1);
    wlog ("", "Insert doc2 in book returned %d.\n", rt);

    rt = book::insert (bookRef, doc3, 1);
    wlog ("", "Insert doc3 in book returned %d.\n", rt);

    rt = book::position (bookRef, doc1);
    wlog ("", "Position of '%s' in book : %d\n", doc1, rt);

    rt = book::position (bookRef, doc3);
    wlog ("", "Position of '%s' in book : %d\n", doc3, rt);

    wlog ("", "Style source is '%s'\n", book::get_master (bookRef));
    rt = book::set_master (bookRef, doc2);
    wlog ("", "Set style source returned : %d\n", rt);
    wlog ("", "Style source is now '%s'\n", book::get_master (bookRef));

    rt = book::save (bookRef);
    wlog ("", "Saving book returned : %d\n", rt);
    return 0;
}

Open an existing book and write all documents of the book to the global logfile.

int main ()
{
    ItemRef		bookRef	= item::alloc ();
    int       	rt, i;
    char		doc1[256];
    char		bookPath[256];

    strcpy (bookPath, "$DESKTOP/book.indb");
    rt = book::open (bookPath, bookRef);
    wlog ("", "Open book returned %d.\n", rt);
    if (rt)	return 0;

    wlog ("", "Book contains %d doc(s)\n", book::count_docs (bookRef));
    for (i = 0; i < book::count_docs (bookRef); i++)
    {
        wlog ("", "Doc %d : '%s'\n", i+1, book::nth_doc (bookRef, i));
    }

    return 0;
}

Remove a document from an existing book.

int main ()
{
    ItemRef		bookRef	= item::alloc ();
    int     	 	rt;
    char		bookPath[256];
    char		doc3[256];
    char*		masterDoc;

    strcpy (bookPath, 	"$DESKTOP/book.indb");
    strcpy (doc3, 		"$DESKTOP/book3.indd");
    rt = book::open (bookPath, bookRef);
    wlog ("", "Open book returned %d.\n", rt);
    if (rt)	return 0;

    rt = book::remove (bookRef, doc3);
    wlog ("", "Removing doc3 in book returned %d.\n",	rt);

    rt = book::save (bookRef);

    return 0;
}

Export a book to a PDF file using the defined export style 'Vorschau'.

int main ()
{
    ItemRef		bookRef	= item::alloc ();
    int       	rt;
    char		bookPath[256];

    strcpy (bookPath, "$DESKTOP/book.indb");
    rt = book::open (bookPath, bookRef);
    if (rt)	return 0;
    rt = book::export_ (bookRef, "", "Vorschau");
    wlog ("", "Export book returned %d.\n", rt);

    book::save (bookRef);
    return 0;
}

Author

Paul Seidel

Version

16.10.2024, 11:40 Uhr

Since

Plugin Version 1.4.2 R 505

Alphabetic index HTML hierarchy of classes or Java