Document methods.

Last Change :
24.04.2025, 13:54 Uhr

Document methods.

static ItemRef document::alloc(char* path)

Create a reference to an open document.

Name Type Default Description
Return ItemRef   Reference to the document. Release this reference as soon as possible using item::release. 0 : document not found
path String or char* - Complete path to the document file or "Unnamed-1", ... in case of new documents.

Create ItemRefs of two open documents. Together with item::define, you can use this to address a frame for which you know the document path and the UID. 

int main ()
{
    ItemRef			d1		= document::alloc ("$DESKTOP/a1.indd");
    ItemRef			d2		= document::alloc ("Unnamed-1");

    wlog ("", "a1	: %d\n", item::getint (d1));
    item::define (d1, d1, 123);	// Frame 123 of a1.indd
    wlog ("", "Neu	 : %d\n", item::getint (d2));
    item::define (d2, d2, 456);	// Frame 456 of Unnamed-1

    return 0;
}

The UID 0 always points to a document. The examples creates an ItemRef to the document of the current frame an shows the documents name. 

int main ()
{
    ItemRef			docRef	= item::alloc ();
    char			docName	[4000];

    item::define (docRef, gFrame, 0);
    document::name (docName, docRef);
    showmessage (docName);

    return 0;
}

v3.3 R2851, 12.04.2012

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static int document::is_valid(ItemRef docRef)

Does the reference point to an existing document?

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

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

Version 1.4.1 R383, 28. June 2007

priint:comet InDesign® Plug-Ins, Illustrator

item::defined

static ItemRef document::current()

Ascertain the InDesign® document of the script. The variable may not be deleted.

Name Type Default Description
Return ItemRef   Current InDesign® document or 0

Version 1.1.7, Januar 2005

priint:comet InDesign® Plug-Ins, Illustrator

document::get_front
document::select

static ItemRef document::get_front()

Get the front document.

Name Type Default Description
Return ItemRef   Reference to the front document.
useStatic int 0 Should a static varibale be used for the determined reference or should the reference be automatically allocated?

0 : Allocate return value. In this case, the return value must be deleted again with item::release!

1 : Use an internal static variable as return. The content will be overwritten the next time the function is called!

Parameter useStatic since v5.0 R36580, 21. April 2025 Version 2.1 R1800, 15. March 2010

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

document::current
document::select
comet.document.getFront

static int document::count()

How many documents are open in the moment?

Name Type Default Description
Return int   Number of open documents

v3.3 R2851, 12. Apr 2012

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

comet.document.getOpen

static char* document::get_nth(int n, ItemRef outRef = 0)

Path or window title of n-th opened document.

Name Type Default Description
Return char*   Path of the document file or window title in case of new documents

The return value must not be changed and will be overwritten in subsequent calls of the function. See here to learn more about functions returning r/o char* values.

n int - 0 based index of document
outRef ItemRef 0 If the function is executed successfully, the variable contains a reference to the opened document

0 : Ignore>
otherwise: Reference object created with item::alloc

Get the number of all opened documents and write all paths of the opened documents to the log file in a loop. 

int main ()
{
    int		i;
    int		docs	= document::count ();

    for (i = 0; i < docs; i++)
    {
        wlog ("", "%d : '%s'\n", i+1, document::get_nth (i));
    }

    return 0;
}

v3.3 R2851, 12. Apr 2012
Parameter outRef since v4.1.8 R27542, 22. Sept. 2020

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

comet.document.getOpen

static int document::select(ItemRef docRef)

Set the current front document. Since most script functions work on the current front document, you can use this call to cause your script to start the processing in another document..

The call also works in InDesign® Server.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)

Version 2.1 R1800, 15. March 2010
InDesign® Server support since v4.1.8 R27552, 23. Sep. 2020
comet_pdf support since v4.3 R34040, 14. Dec 2023

priint:comet InDesign® Plug-Ins, Illustrator, comet_pdf

document::current
document::get_front
document::count
document::get_nth
document::select_by_name, app.comet.documentOpen
comet.CDocument.setFront

static int document::select_by_name(char* pp)

Set the current front document. Most script functions are working on the current front document. So with this call you can cause your script to change its destination document. The document is selected by its name or the file path.

Name Type Default Description
Return int   Fehlercode or 0
pp String or char* - Name, window title or full path of the documents file. For unsaved new documents, the documents name or window title are used only. It applies:

Specification without path delimiter : search only by name or window title

Specification with path delimiter : Search for the complete path

v4.1.8 R27542, 22. Sep. 2020
Search by window title since v4.3 R34250

priint:comet InDesign® Plug-Ins

document::current
document::get_front
document::count
document::get_nth
document::select, app.comet.documentOpen

static ItemRef document::create(
  float width = -1.0,
  float height = -1.0,
  int pages = 1,
  int pagesPerSpread = 1,
  float scale = 1.0,
  int left = 0,
  int top = 0,
  int right = 0,
  int bottom = 0,
  int columns = 1,
  float gutter = 12.0,
  int direction = 0,
  int restartPageNums = -1,
  int bindingDirection = -1,
  int intent = -1,
  float ml = -1.0,
  float mt = -1.0,
  float mr = -1.0,
  float mb = -1.0,
  int startPageNum = -1)

Create a new empty document.

Name Type Default Description
Return ItemRef   Reference to the newly created document. The reference is allocated by the call and must be released again with item::release!
width float -1.0 Page width in points

≤ 0.0 : Page width of the current document, 595.276pt (DIN A4) if no document is open.
height float -1.0 Page height in points

≤ 0.0 : Page height of the current document, 841.89 (DIN A4) if no document is open.
pages int 1 Number of pages

≤ 0 : Number of pages of the current document, 1 if no document is open.
pagesPerSpread int 1 Pages per spread

≤ 0 : Pages per spread of the current document, 2 if no document is open.
scale float 1.0 Scaling in the document window, 1.0 corresponds to 100%
left, top, right, bottom int 0 each Position and size of the document window in pixels (ATTENTION : The values are integers (int)!). The values are only applied if all four values are specified and if left < right and top < bottom.
columns int 1 Number of columns on the pages.

≤ 0 : Number of columns on the first page of the current document, 1 if no document is open.
gutter float 12.0 Column spacing in points. The parameter is only evaluated if the number of columns is greater than 0.

≤ 0 : Column spacing in the first page of the current document, 12.0 if no document is open.
direction int 1 Direction of the document columns. The parameter is only evaluated if the number of columns is greater than 0.

0 : Horizontal
1 : Vertical
2 : Roman
3 : CJK
< 0 : Column direction of the first page of the current document, 1 (vertical) if no document is open.
restartPageNums int -1 Restart page numbering? The specification is only used when the document is used in books (see book).

-2 : Setting of the current document, ignore if no document is open.
-1 : Ignore
0 : No
1 : Yes
bindingDirection int -1 Page binding.

-2 : Setting of the current document, ignore if no document is open.
-1 : Ignore
0 : Left to right
1 : Right to left
2 : Default setting of InDesign®
intent int -1 Document intention. Ignored by comet_pdf.

-2 : Setting of the current document, ignore if no document is open.
-1 : Ignore
0 : Print
1 : Web
2 : Mobile
ml, mt, mr, mb float alle -1.0 Page marginsin points
  • left (inside for multi-page spreads)
  • top
  • right (outside for multi-page spreads)
  • bottom
-2.0 : Setting the current document, 36.0 if no document is open.

-1.0 : Default 36.0

> -1.0 and < 0.0 : Percentage of the page (0.1 corresponds to 10%)

≥ 0.0 : Absolute value in points
startPageNum int -1 Mit welcher Sewitennummer soll das Dokument beginnen?

-2 : Setting of the current document, ignore if no document is open.
-1 : Ignore
> 0 : Page number (1-based)
#include "internal/types.h"

The script creates a new empty document in the size of the current document and inserts two frames into this document. The document is then saved as abc.(indd | w2ml) on your desktop. The script works for InDesign and comet_pdf. 

#include "internal/types.h"
#include "internal/text.h"

int main ()
{
    ItemRef		docRef;
    ItemRef		fr	= item::alloc ();

    docRef = document::create (
     		-1.0, -1.0,					// size
     		-1, -1,						// pages, pagesPerSpread
     		1.0, 0, 0, 0, 0,			// window
     		1, 12.0, 1,					// columns
     		-1,							// restart numbering
     		-1,							// binding
     		-1,							// intent
     		100.0, -2.0, -2.0, -2.0,	// margins
     		-2							// start page num
    );

    document::select (docRef);
    frame::create (fr, kRectangle, 0.0, 0.0, 200.0, 50.0, 1);
    frame::color_rgb (fr, 255, 128, 0);
    frame::replace (fr, "Please work!");

    frame::create2 (fr, kRectangle, 0.0, 0.0, 100.0, 100.0, 1);
    frame::color_rgb (fr, 0, 128, 0);

    document::saveas (docRef, "$DESKTOP/abc");

    item::release (docRef);
    item::release (fr);

    return 0;
}

Parameter columns, ... mb since Comet 3.1 R2187, 26.10.2010br/> Parameter startPageNum since v4.3 R34040, 14. Dez 2024
Revision of the default values v4.3 R34040, 14. Dez 2024

priint:comet InDesign® Plug-Ins, comet_pdf

static ItemRef document::open(
  char* path,
  float scale = 1.0,
  int left = 0,
  int top = 0,
  int right = 0,
  int bottom = 0,
  int visibility = 1,
  int appendToRecent = 1,
  int uiFlags = kSuppressUI,
  int parenting = -1)

Open an InDesign® document. InDesign® Server ignores all visibility information (paramenter scale and following).

Name Type Default Description
Return ItemRef   Reference to the newly created documented, with item::release to delete
path String or char* - Complete path to the file to be opened.

In case of comet_pdf, the extension indd is replace automatically by w2ml.
scale float 1.0 Current scale
left int 0 Window position
top int 0 Window position
right int 0 Window position
bottom int 0 Window position
visibility int 1 Window visible / hidden

0 : No, only use in background
1 : Yes. The document will get the new front document. Script functions working on the front document will use this document instead of the callimg document. Since v4.1 R22423 the same is true for InDesign® Server.
appendToRecent int 1 Insert the file to the Recent documents menu?

0 : No
1 : Yes
uiFlags int kSuppressUI Dialogs to show
kSuppressUI :Suppress all dialogs and progress bars
kMinimalUI : Even show certain dialogs
kFullUI : Show all dialogs and progress bars
parenting int -1 The parenting allow a caller to specify how and where a new presentation will be created, optionally in relation to an existing presentation. InDesign supports the following (undocumented by Adobe) values:

-1 : Ignore value
0 : InDesign® Default
1 : NewFloatingDock
2 : NewFloatingDock_ObscureRelative
3 : NewFloatingDock_DontObscureRelative
4 : AsSiblingOfRelative
5 : InNewTabGroupFromRelative
6 : InNewPaneFromRelative
7 : AsSiblingToLeftOfRelative
8 : AsRightmostChildOfParent
#include "internal/types.h"

Open and show a document. Alerts for missing fonts, links, ... are suppressed. 

#include "internal/types.h"

int main ()
{
    ItemRef	doc	= document::open ("$DESKTOP/paul.indd", 
     		1.0,
     0, 0, 0, 0,
     	1,
     	1,
     	kSuppressUI);

    return 0;
}

Open and show a document 

#include "internal/types.h"

int main ()
{
    ItemRef	doc	= document::open ("$DESKTOP/paul.indd", 
     		1.0,
     0, 0, 0, 0,
     	1,
     	1,
     	kFullUI);

    return 0;
}

appendToRecent since Version 2.1 R1650, 11.11.2009
Parameter uiFlags since version 2.1 R1820, 30.03.2010
Parameter parenting since v4.0.5 R16000, 7. Feb 2010

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

comet.document.open

static ItemRef document::open_copy(
  char* path,
  float scale = 1.0,
  int left = 0,
  int top = 0,
  int right = 0,
  int bottom = 0,
  int visibility = 1,
  int appendToRecent = 1,
  int uiFlags = kSuppressUI)

Open a copy of an InDesign® document. InDesign® Server ignores all visibility information (paramenter scale and following).

Name Type Default Description
Return ItemRef   Reference to the newly created documented, with item::release to delete
path String or char* - Complete path to the file to be opened.
scale float 1.0 Current scale
left int 0 Window position
top int 0 Window position
right int 0 Window position
bottom int 0 Window position
visibility int 1 Window visible / hidden

0 : No, only use in background
1 : Yes. The document will get the new front document. Script functions working on the front document will use this document instead of the callimg document.
appendToRecent int 1 Insert the file to the Recent documents menu?

0 : No
1 : Yes
uiFlags int kSuppressUI Dialogs to show
kSuppressUI :Suppress all dialogs and progress bars
kMinimalUI : Even show certain dialogs
kFullUI : Show all dialogs and progress bars
parenting int -1 The parenting allow a caller to specify how and where a new presentation will be created, optionally in relation to an existing presentation. InDesign supports the following (undocumented by Adobe) values:

-1 : Ignore value
0 : InDesign® Default
1 : NewFloatingDock
2 : NewFloatingDock_ObscureRelative
3 : NewFloatingDock_DontObscureRelative
4 : AsSiblingOfRelative
5 : InNewTabGroupFromRelative
6 : InNewPaneFromRelative
7 : AsSiblingToLeftOfRelative
8 : AsRightmostChildOfParent
#include "internal/types.h"

appendToRecent since Version 3.1 R1650, 11.11.2009
Parameter uiFlags since version 2.1 R1820, 30.03.2010
Parameter parenting since v4.0.5 R16000, 7. Feb 2010

priint:comet InDesign® Plug-Ins, comet_pdf

static int document::set_display_name(ItemRef doc, char* name)

Set the display name of the document. Set the displayed name of a document. This name is used as the window title and as a suggestion for the filename when using File -> Save As.

The displayed name is not the filename. Changes to the display name are not applied to the document and will be lost when the document is closed.

Name Type Default Description
Return int   ErrorCode or 0
doc ItemRef 0 Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
name String or char* - New display name for the document window of the document

Set the name of the current document 

char* newName = "HelloWorld";

document::set_display_name(gDocument, newName);

@since Version 4.0.5 R8202, 17. June 2015

priint:comet InDesign® Plug-Ins

get_display_name
comet.CDocument.setDisplayName

static char* document::get_display_name(char* result, ItemRef docRef = 0)

Title of the document in the document window. In the standard case, the file name (or Unnamed-N for new documents) is used as window title. If the window title was changed by document::set_display_name, the function returns the changed window title.

Name Type Default Description
Return String or char* (Depends on parameter result)   Window title of the document

For better use of the function, result is used as the return value.
result String or char* - Reserved memory for result

0 : [since v4.3 R33094] Return result in a static r/o variable of the Script Engine. The variable must not be changed. The next time the function is called, the content will be overwritten!
docRef ItemRef 0 Document specification.

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)

v4.1.8 R27600, 7. Okt. 2020

priint:comet InDesign® Plug-Ins, comet_pdf

document::set_display_name
document::name
comet.CDocument.getDisplayName

static int document::is_opened(char* path, ItemRef docRef = 0)

Shows whether a document is opened or not.

Name Type Default Description
Return int   1 if the document is opened, else 0
path String or char* - complete path to the document.
docRef ItemRef 0 After successful return it contains a reference to the document. Must be allocated before using item::alloc

Check whether a docuemt is already opened, and if not, open it. Be care to delete the used reference before calling document::open, this call will create a new reference. 

ItemRef		docRef		= item::alloc ();
int 		wasOpened 	= document::is_opened (path, docRef);

if (!wasOpened)
{
    item::release (docRef);
    docRef = document::open (path, docRef);
}

:

if (wasOpened) document::close(docRef);

docRef seit Version 2.1 R1800, 15. March 2010

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static int document::can_save(ItemRef docRef = 0)

Can the given document be saved? The function checks whether a document shows an existing file.

Opened and unchanged documents of the current InDesign version can be saved!

Name Type Default Description
Return int   1 : Document of the current InDesign version. The document may be unchanged at the time of the question!

0 : The document shows one of the following files:
  • NNew unsaved document
  • Converted unsaved document from an older InDesign version
  • Opened and unsaved IDML file
  • Opened and nsaved W2ML file
docRef ItemRef 0 Reference to an open document

0 : Script document or current front document if the script has no document.

Check whether the current document can be saved. 

int main ()
{
    if (document::can_save ()) wlog ("", "The current document can be saved.\n");
    else wlog ("", "The current document has no file path.\n");

    return 0;
}

v5.0, R36580, 21. April 2025

static int document::close(
  ItemRef docRef,
  int saveOnClose = 1,
  int uiFlags = kSuppressUI,
  int allowCancel = 1,
  int mode = kSchedule)

Closing a document. Closing documents can force a lot of actions on the document. InDesign® therefore schedules document closing to the next idle time. With kProcess you can force direct closing, but this may cause serious problems!

[Since v4.3 R35200] Panel and Front Row scripts can be undone in one single step. Because saving or closing the current script document would end the 'recording' of this sequence, InDesign sometimes refuses to save or close the current document (Error 3590). However, once a document has been saved or closed, undo is no longer possible anyway. In these cases, you can also do without 'Recording'. To do this, add the note -- Disable Undo -- (in exactly this spelling!) in a comment anywhere in your script.

cScript und Javascript 

// -- Disable Undo --

Python 

# -- Disable Undo --

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document to close

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
saveOnClose int 1 save before close?
0 : Do not save, changes are omitted
1 : Save
uiFlags int kSuppressUI Dialogs to show
kSuppressUI :Suppress all dialogs and progress bars
kMinimalUI : Even show certain dialogs
kFullUI : Show all dialogs and progress bars
allowCancel int 1 Cancel allowed? Not supported while uiFlags kSuppressUI or mode kImmediate is set
0 : Forbidden
1 : Allowed
mode int kSchedule Close Mode

kSchedule : Close normally on next idle time

kProcess : Close right now. This may cause seriuos problems even on changed files!

kImmediate : since v4.1 R24666 Close immediately. This is an attempt to circumvent the InDesign® problems with kProcess. Unfortunately, we cannot promise that this will work in every case - but it is worth a try.
#include "internal/types.h"

v3.4
kImmediate since v4.1 R24666, 11. Jan 2019

priint:comet InDesign® Plug-Ins, Illustrator

comet.CDocument.close

static int document::close_by_name(
  char* docPath,
  int saveOnClose = 1,
  int uiFlags = kSuppressUI,
  int allowCancel = 1,
  int mode = kSchedule)

Closing a document. Closing documents can force a lot of actions on the document. InDesign® therefore schedules document closing to the next idle time. With kProcess you can force direct closing, but this may cause serious problems!

[Since v4.3 R35200] Panel and Front Row scripts can be undone in one single step. Because saving or closing the current script document would end the 'recording' of this sequence, InDesign sometimes refuses to save or close the current document (Error 3590). However, once a document has been saved or closed, undo is no longer possible anyway. In these cases, you can also do without 'Recording'. To do this, add the note -- Disable Undo -- (in exactly this spelling!) in a comment anywhere in your script.

cScript und Javascript 

// -- Disable Undo --

Python 

# -- Disable Undo --

Name Type Default Description
Return int   0 or ErrorCode
docPath String or char* - Full path of document to close
saveOnClose int 1 save before close?
0 : Do not save, changes are omitted
1 : Save
uiFlags int kSuppressUI Dialogs to show
kSuppressUI :Suppress all dialogs and progress bars
kMinimalUI : Even show certain dialogs
kFullUI : Show all dialogs and progress bars
allowCancel int 1 Cancel allowed? Not supported while kSuppressUI or mode kImmediate is set
0 : Forbidden
1 : Allowed
mode int kSchedule Close Mode

kSchedule : Close normally on next idle time

kProcess : Close immediatally. This may cause seriuos problems even on changed files!

kImmediate : since v4.1 R24666 Close immediatally. This is an attempt to circumvent the InDesign® problems with kProcess. Unfortunately, we cannot promise that this will work in every case - but it is worth a try.
#include "internal/types.h"

v3.4
kImmediate since v4.1 R24666, 11. Jan 2019

priint:comet InDesign® Plug-Ins

static int document::save(
  ItemRef docRef,
  int uiFlags = kSuppressUI,
  int millisec = 0,
  int repeat = 0)

Saving a document.

Due to a bug in InDesign®, saved documents can come in an unsaved state after a short time. If you type in some text and save the document using Command-S very quickly you can see this behavior. Same things happens if you change some text inside a script and save the document. To get a reall saved document, you can save the document in the next idle time, and (we couldn't find out, when InDesign® fires the document changes) you can repeat saving some times. Good results we got with 300 milli seconds after idle time and 5 to 8 repetiions.

Using idle time saving means, the document is NOT saved on funtion return!

[Since v4.3 R35200] Panel and Front Row scripts can be undone in one single step. Because saving or closing the current script document would end the 'recording' of this sequence, InDesign sometimes refuses to save or close the current document (Error 3590). However, once a document has been saved or closed, undo is no longer possible anyway. In these cases, you can also do without 'Recording'. To do this, add the note -- Disable Undo -- (in exactly this spelling!) in a comment anywhere in your script.

cScript und Javascript 

// -- Disable Undo --

Python 

# -- Disable Undo --

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document to save

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
uiFlags int kSuppressUI Dialogs to show
kSuppressUI :Suppress all dialogs and progress bars
kMinimalUI : Even show certain dialogs
kFullUI : Show all dialogs and progress bars

Ignored by comet_pdf.
millisec int 0 Time to save the document in milli seconds after idle time starts

0 : ignore (save right now)
>0 : Duration after idle time start
<0 : Automatic saving of the document every millisecs

Ignored by comet_pdf & Illustrator.
repeat int 0 (only if > 0) Number of tries

Ignored by comet_pdf & Illustrator.
#include "internal/types.h"

Parameter millisec and repeat since Version 3.1 R1840, 27. April 2010

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

comet.CDocument.save

static int document::saveas(
  ItemRef docRef,
  char* path,
  int uiFlags = kSuppressUI)

Saving a document using a given destination path. The function will change the the window of the given document to the 'save as' file.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document to save as

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
path String or char* - Full path of the new document. The file extension is automatically replaced/added by InDesign and comet_pdf. If the target folder does not exist, it is created automatically.

Illustrator: To save file as EPS use file extension ".eps".
uiFlags int kSuppressUI Dialogs to show
kSuppressUI :Suppress all dialogs and progress bars
kMinimalUI : Even show certain dialogs
kFullUI : Show all dialogs and progress bars

Ignored by comet_pdf and Illustrator.
#include "internal/types.h"

Save as EPS for Illustrator since v4.2 R29182
Automatic replacement/addition of the appropriate file extension (indd resp. w2ml) since v4.3 R34040, 14. Dec 2023 v2.0

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

comet.CDocument.saveAs

static int document::revert(ItemRef docRef = 0)

Revert document to last saved version.

Calls to this function may close and re-open documents. References to gFrame, references to tables, etc. will point to non-existent objects and their usage can crash InDesign® immediatelly!

Name Type Default Description
Return int   0 or ErrorCode

1280 : New unsaved or unmodified document

If the given document was found, the command always returns 0 in comet_pdf.
docRef ItemRef 0 Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)

v4.0.5 R10000, 5. Feb 2015

priint:comet InDesign® Plug-Ins, comet_pdf

static char* document::name(char* result, ItemRef docRef = 0)

File name of the current document. For the entry a string is expected which has sufficient reserved memory (min. 256), in order to handle the result. The function will not provide any result for new unsaved documents.

Name Type Default Description
Return String or char* (Depends on parameter result)   Name of the current document, pointer to result
result String or char* - Reserved memory for result

0 : [since v4.3 R33094] Return result in a static r/o variable of the Script Engine. The variable must not be changed. The next time the function is called, the content will be overwritten!
docRef ItemRef 0 Document specification.

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)

Get the name of the current document 

char		name[256];

showmessage (document::name (name));

The parameter doc is valid from version 1.1.7, Januar 2005

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

document::path
document::path9
document::pathX
document::folder
comet.CDocument.getName

static char* document::path9(char* p, ItemRef docRef = 0)

File path including file name of the given document. On the Mac, the result is returned in MacOS 9 notation with drive name and ':' as path delimiter.

Yes! You wouldn't believe it: The last Mac OS 9 is over 20 years ago. But the InDesign menu 'Recent Files' and the 'Links' panel still showing Mac OS 9 paths, as well as the the InDesign SDK uses this style of paths.

For the entry a string is expected which has sufficient reserved memory (min. 1024), in order to handle the result. The function will not provide any result for new unsaved documents.

Name Type Default Description
Return String or char*   (Depends on parameter p) Complete MacOS 9 path of the given document, pointer to p
p String or char* - Reserved memory for the result

0 : [since v4.3 R33094] Return result in a static r/o variable of the Script Engine. The variable must not be changed. The next time the function is called, the content will be overwritten!
docRef ItemRef 0 Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)

Get the name of the current document 

char		p[256];

showmessage (document::path9 (p));

The parameter doc is valid from version 1.1.7, Januar 2005

priint:comet InDesign® Plug-Ins, comet_pdf

document::name
document::path
document::pathX
document::folder

static char* document::path(char* p, ItemRef docRef = 0)

File path including file name of the given document. For the entry a string is expected which has sufficient reserved memory (min. 1024), in order to handle the result. The function will not provide any result for new unsaved documents.

Name Type Default Description
Return String or char*   (Depends on parameter p) Complete path of the given document, pointer to p
p String or char* - Reserved memory for the result

0 : [since v4.3 R33094] Return result in a static r/o variable of the Script Engine. The variable must not be changed. The next time the function is called, the content will be overwritten!
docRef ItemRef 0 Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)

Get the path of the current document 

char		p[1024];

showmessage (document::path (p));

The parameter doc is valid from version 1.1.7, January 2005

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

document::name
document::path9
document::pathX
document::folder
comet.CDocument.getPath

static char* document::pathX(char* p, ItemRef docRef = 0)

File path including the file name of the given document. In the path all Windows path delimiters (\) are replaced with /. This format should always then be used if the path is to be used for internal descriptions (xmlquery, soap, cscript). For the entry a string is expected which has sufficient reserved memory (min. 1024) in order to handle the result. The function will not provide any result for new unsaved documents.

Name Type Default Description
Return String or char*   (Depends on parameter p) Complete path of the given document, pointer to p
p String or char* - Reserved memory for the result

0 : [since v4.3 R33094] Return result in a static r/o variable of the Script Engine. The variable must not be changed. The next time the function is called, the content will be overwritten!
docRef ItemRef 0 Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)

Get the OS X path of the current document 

char		p[1024];

showmessage (document::pathX (p));

The parameter doc is valid from version 1.1.7 January 2005

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

document::name
document::path
document::path9
document::folder

static char* document::folder(char* p, ItemRef docRef = 0)

Folder of the given document without path delimiter (: or /) at the end. For the entry a string is expected which has sufficient reserved memory (mind. 1024) in order to handle the result. The function will not provide any result for new unsaved documents.

Name Type Default Description
Return String or char*   (Depends on parameter p) Complete path of the given document, pointer to p
p String or char* - Reserved memory for the result

0 : [since v4.3 R33094] Return result in a static r/o variable of the Script Engine. The variable must not be changed. The next time the function is called, the content will be overwritten!
docRef ItemRef 0 Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)

Get the folder path of the current document 

char		p[1024];

showmessage (document::folder (p));

The parameter doc is valid from version 1.1.7 January 2005

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

document::name
document::path
document::path9
document::folder

static char* (char* p, ItemRef docRef = 0)

DEPRECATED! Please use the function document::path9 instead and remove the document name from this result.

Please use the function document::path9 instead and remove the document name from this result.

static int document::pages(ItemRef doc = 0)

Number of pages in the document.

Name Type Default Description
Return int   Number of pages in the given document
docRef ItemRef 0 Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)

How many pages does the current document have? 

int p = document::pages ();

Parameter doc since Version 1.1.7, Januar 2005 v1.2

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

page::get
page::get_str
comet.CDocument.getPages

static int document::page(ItemRef docRef = 0)

Current page of a given document.

To make a page the current page, you must click at least once in the page area. A frame does not have to be selected for this, but simple scrolling to the page view is not enough! Using InDesign® Server or comet_pdf the current front page is undefined!

Name Type Default Description
Return int   0 : in case of any erros
otherwise : 1-based current page of the given document

Using InDesign® Server or comet_pdf the current front page is undefined! The function will always return 0
docRef ItemRef 0 Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)

Get the 1-based page number of currently selected page of the current document. 

int p = document::page ();

The parameter doc is valid from version 1.1.7 January 2005
... and removed in 1.4.2 R 612(11. March 2008)

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

page::get
page::get_str
comet.CDocument.getCurrentPage

static char* document::plugin(char* p)

Wich plug-in executes the current cScript?

Name Type Default Description
Return String or char*   (Depends on parameter p) Plugin name (XMLLink)
p String or char* - Reserved memory for the result

Get the name of the execting plugin. 

char		p[1024];

showmessage (document::plugin (p));

Version 1.2.2 (24. November 2005)

priint:comet InDesign® Plug-Ins, comet_pdf

document::name
document::path
document::path9
document::folder

static int document::begin_sequence(char* undo_name = 0)

End the undo sequence of the script and start a new sequence. Undo sequences are a sequence of document changes that can be undone with one undo step. Each script is automatically included in an undo sequence (and can therefore be undone with one Undo).

The length of undo sequences is limited by the amount of data required for the single document changes. Therefore, for very long scripts or scripts with many document changes, it may be necessary to end the current sequence and continue with a new sequence.

The undo sequence is automatically ended by calling the function again or by the end of the script. At the end of the script the last undo sequence is ended automatically.

Using comet_pdf the call has no effect.

Name Type Default Description
Return int   0 or ErrorCode
undo_name String oder char* 0 Name of the sequnces in menue Edit -> Undo ->

0 or "" : "Execute Script"

Version 1.2.2 (24. November 2005)

priint:comet InDesign® Plug-Ins, comet_pdf

document::end_sequence
document::build_products

static int document::end_sequence()

End the undo sequence of the current script. All further document changes by the script can then only be undone in individual steps.

The statement should be used only in cases where you certainly do not need an Undo of the document changes of the script. Then, however, it can significantly speed up the processing. In the normal case you should use document::begin_sequence instead which also ends the current undo sequence - but starts a new sequence at the same time.

Using comet_pdf and in Front Row actions the call has no effect.

Name Type Default Description
Return int   0 or ErrorCode

Export a document to a PDF so that all texts in the document are converted to paths (the so called outlines). To do this, the Javascript command text.createOutline is first used to convert all letters into paths. Then the PDF export is made. Finally, all document changes made are rolled back. Note: It's an example for command sequences only. An easier way to create PDFs with outlined texts is using the option with comet-option outlines:yes of the script command pdf_export. 

// @@ICONID	533

char jsExportOulinedPDF [] = "\n\
var myDocPath 		= '$MYPATH';\n\
var myDocName 		= '$MYNAME';\n\
var myPDFPreset		= '$MYPRESET';\n\
\n\
var gOptions 		= app.comet.ping() + ';-1;';\n\
var inddPath		= myDocPath + '/' + myDocName + '.indd';\n\
var pdfPath			= myDocPath + '/' + myDocName + '.pdf';\n\
\n\
function main() \n\
{\n\
    for (var n = 0; n < app.documents.length; n++)\n\
    {\n\
        doc         = app.documents [n];\n\
        \n\
        if (doc.saved && File (doc.fullName).fullName == File (inddPath).fullName)\n\
        {\n\
            var 	par		= doc.stories.everyItem().paragraphs.everyItem().getElements();\n\
            var 	parLen	= par.length;\n\
            \n\
            for (var i = 0; i < parLen; i++)\n\
            {\n\
                var 		para = par [i];\n\
                try			{ para.createOutlines(true); } \n\
                catch(e) 	{ }\n\
            }\n\
            try 			{ app.comet.documentGeneratePDF (inddPath, '$MYPRESET', pdfPath, gOptions); }\n\
            catch (e)		{ }\n\
            \n\
            break;\n\
        }\n\
    }\n\
}\n\
\n\
app.comet.documentOpen (inddPath, true, gOptions);\n\
app.doScript(main, ScriptLanguage.JAVASCRIPT, undefined, UndoModes.ENTIRE_SCRIPT, 'Generate PDF with Outlined Texts');\n\
";

int main ()
{
    char 		docPath 	[512];
    char 		docName 	[512];
    char 		shortName 	[512];
    String		js1			= string::alloc (jsExportOulinedPDF);
    int 		seq;

    string::replace (js1, "$MYPATH", document::folder (docPath, 0));
    string::replace (js1, "$MYNAME", file::shortname (shortName, document::name (docName, 0)));
    string::replace (js1, "$MYPRESET", "");

    seq = document::end_sequence (0);
    seq = document::open_sequence ("Hola paul");

    run_javascript (js1, 0, 1, 0);

    document::close_sequence (seq, 1);

    return 0;
}

Version 1.2.2 (24. November 2005)

priint:comet InDesign® Plug-Ins, comet_pdf

document::begin_sequence

static int document::open_sequence(char* name = 0)

Open a command sequence. You can commit or rollback all following document changes by a subsequent call to close_sequence.

Please take care to close all command sequences by an according call to close_sequence. You may nest sequences but never merge: The last opened sequence must be the first to close always!

Under comet_pdf the function does nothing.

Name Type Default Description
Return int   0 : Error
otherwise : ID of opened sequence
name char* 0 Name of sequence for showing it in the Undo menu of InDesign®

The frame will get a new text, but the orange color is rolled back. 

int main ()
int main ()
{
    int 			seq;

    frame::replace (gFrame, "abcde");

    seq = document::open_sequence ("Hola paul");
    frame::color_rgb (gFrame, 255, 128, 0);
    document::close_sequence (seq, 0);

    return 0;
}

v4.0.5 R20031, 30. Aug 2017

priint:comet InDesign® Plug-Ins, comet_pdf

document::close_sequence

static int document::close_sequence(int seqID, int state = 1)

Close a opened sequence and commit or rollback changes.

Please take care to close all command sequences by an according call to close_sequence. You may nest sequences but never merge: The last opened sequence must be the first to close always! Close a sequence only one time!

Under comet_pdf the function does nothing.

Name Type Default Description
Return int   0 or error code
seqID int - ID of sequence from open_sequence
state int 1 1 : Commit changes
0 : Rollback changes

Replace the text of the frame with 'abcde'. In a separate sequence the frame is then filled orange- but the color change is immediately rolled back. 

int main ()
{
    int 			seq;

    frame::replace (gFrame, "abcde");

    seq = document::open_sequence ("Hola paul");
    frame::color_rgb (gFrame, 255, 128, 0);
    document::close_sequence (seq, 0);

    return 0;
}

v4.0.5 R20031, 30. Aug 2017

priint:comet InDesign® Plug-Ins, comet_pdf

document::close_sequence

static int ()

With long script actions it is sometimes the case that the undo memory managed internally by InDesign® can overflow. Not supported by InDesign® CS3. In this event a message is automatically displayed indicating that the complete action is too large and cannot be reversed. This message is not very useful - it forces the progress to wait until users have responded. A call of the function will flush the undo stack. Prior to the call the document::begin_sequence must be executed.

Under comet_pdf the function does nothing.

Version 1.2.2 (24. November 2005)

priint:comet InDesign® Plug-Ins, comet_pdf

Not supported since InDesign® CS3.
document::open_sequence
document::close_sequence
document::end_sequence

static int document::load(
  DBC dbc,
  char* attribute,
  char* table_,
  int ID,
  char* creationPath,
  float scale = -1.0,
  int left = 0,
  int top = 0,
  int right = 0,
  int bottom = 0,
  int appendToRecent = 1)

Create and open a document from a database template. The generated ItemRef must be deleted again from the script. Dokuments can be stored in the database with store_macro.

Name Type Default Description
Return ItemRef   Reference to the newly created documented, with item::release to delete!!
dbc DBC - Database connectio (ODBC or OCI)

0 : current database connection
attribute String or char* - Attribute name of the database table in which the template is stored
table_ String or char* - Name of the database table in which the template is stored
ID int - ID under which the template is stored in the database
creationPath String or char* - Path for the created file
scale float 1.0 Current scale
left int 0 Window position
top int 0 Window position
right int 0 Window position
bottom int 0 Window position
appendToRecent int 1 Insert the file to the Recent documents menu?

0 : No
1 : Yes 
docRef = document::load (attribute, table_, ID, creationPath
[, scale,
[, left, top, right, bottom]]);

appendToRecent since Version 2.1 R1650, 11.11.2009

priint:comet InDesign® Plug-Ins

document::store_macro

static int ()

DEPRECATED! Update the presentation of the complete document.

1.0.19

priint:comet InDesign® Plug-Ins, comet_pdf

Please use the functions textmodel::force_redraw and document::force_redraw instead of this function.

static int document::set_startpage(
  int startpage,
  int style = 0,
  ItemRef docRef = 0)

Set the start page of a document. Apart from the start page the numbering format (numbers, Roman numerals, letters) can also be specified.

Name Type Default Description
Return int   0 or ErrorCode
startpage int - Start page number
style int 0 Numbering format

0 : 1, 2, 3, 4, ...
1 : I, II, III, IV, ...
2 : i, ii, iii, iv, ...
3 : A, B, C, D, ...
4 : a, b, c, d, ...
docRef ItemRef 0 The document.

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front) 
err_code = document::set_startpage (i, 2);

The numbering format can be specified from version 1.0.20.
The parameter doc is valid from version 1.1.7 January 2005

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CDocument.setStartPage

static int document::store_macro(
  DBC dbc,
  char* attribute,
  char* table_,
  int ID,
  char* preview = "",
  int preview_size = 200,
  char* leftPos = 0,
  char* topPos = 0,
  char* rightPos = 0,
  char* bottomPos = 0,
  int formatID = 1)

Save the current frame selection to the database. The target attribute must be a blob. If the attribute name preview is not empty, a preview of the stored selection will be stored there.

Name Type Default Description
Return int   0 or ErrorCode
dbc DBC - target database
attribute String or char* - Attribute name of the database table in which the template is to be stored
table_ String or char* - Name of the database table in which the template is to be stored
ID int - ID under which the template is stored in the database
preview String or char* '' != "" -> Write a preview in the specific attribute
preview_size int 200 Size of the preview in pixels
leftPos String or char* "" != "" : Calculate the frames bounding box and write the left position to ths database attribute
topPos String or char* "" != "" : Calculate the frames bounding box and write the top position to ths database attribute
rightPos String or char* "" != "" : Calculate the frames bounding box and write the right position to ths database attribute
bottomPos String or char* "" != "" : Calculate the frames bounding box and write the bottom position to ths database attribute
formatID int 1 Format of template
1: Classic (InDesign® document)
2: Snippet (InDesign® document)
3: IDML (CS4, not supported for now) 
err_code = document::store_macro (dbc, attr, table_, id 
[, preview
[, preview_size]]);

v1.2

priint:comet InDesign® Plug-Ins

document::load
document::insert_macro

static ItemList document::insert_macro(
  DBC dbc,
  char* attribute,
  char* table_,
  int ID,
  float x = -1000.0,
  float y = -1000.0,
  int page = -1,
  char* layer = 0,
  int id1 = 0,
  int id2 = 0,
  int id3 = 0,
  char* stringid = 0,
  int autoLoad = 0,
  int classID = 0)

Define a database-stored template within the given document. It is recommended that the general function document::place_items is used to insert the templates.

If you call the function from inside a load placeholder, you should take care to import the frames only once. You may use frame::remove_sub_cometgroups if the placeholder makes only one import.

When inserting a template the Template-ID script of this template can decide to use another template instead. For more information see Description of panel 'Templates' and und TemplateID script.

Name Type Default Description
Return ItemList   Inserted frames must be deleted again with itemlist::release
dbc DBC - Database in which teh template is stored

0 : Use the curent data base
attribute String or char* - Attribute name of the database table in which the template is stored

If attribute and table are empty, the default source for templates is used, you have to give only the template ID.
table_ String or char* - Name of the database table in which the template is stored

If attribute and table are empty, the default source for templates is used, you have to give only the template ID.
ID int - ID under which the template is stored in the database
x float Original position Page relative position in points
y float Original position Page relative position in points
page int Original page Page number on which the template is to be located
layer String or char* Current layer Target layer on which the template is to be placed
id1, id2, id3, stringid int, int, int, char* 0, 0, 0, "" Product ID of the object linked against the template (used also for the Template-ID script, if any script is defined inside the given template). If id1 is 0, linking against the new object is suppressed.
autoLoad int 0 Link, load and build placeholders of the inserted frames automatically.

0 : No, do not link nor load placeholders

1 : Yes, link, load and rebuild (if nesseccary) all inserted frames. Suppressed, if id1 = 0!

-1 : since v3.3.1 R5125 Only link but not load placeholders. Suppressed, if id1 = 0!
classID int 0 Do only deal with placeholders of the given class ID

0 : Ignore class ID. Link, load and build all placeholders
othwise : Do only link, load and build placeholders with the given class id. 
items = document::insert_macro (dbc, attr, table_, id
[, x, y
[, page
[, layer]]]);

id1, id2, id3, stringid since version 1.4 R340, 8. May 2007

autoLoad, classID since version 1.4.2 R528, 17. Dec. 2007

autoLoad == -1 seit v3.3.1 R5126, 22. Jan 2014

priint:comet InDesign® Plug-Ins, comet_pdf

document::store_macro
pages
layer

static ItemList document::place_items(
  DataPool pool,
  char* attribute,
  char* table_,
  int ID,
  float x = -1000.0,
  float y = -1000.0,
  int page = -1,
  char* layer = "",
  int id1 = 0,
  int id2 = 0,
  int id3 = 0,
  char* stringid = 0,
  int autoLoad = 0,
  int classID = 0,
  int addToCometGroup = 1)

Insert a template saved in the database or in a file into the given document. If the template is saved as a file the file must be located in the pool data folder (datapool::get_files) in the subfolder table_/attribute under the name ID.indd.

If you call the function from inside a load placeholder, you should take care to import the frames only once. You may use frame::remove_sub_cometgroups if the placeholder makes only one import.

To import frames from an InDesign® document or snippet not coming from the current data pool use the function place_indesign..

The return value of the function is a new allocated itemlist (the list of imported frames). This list will released on the end of the script automatically. But looped calls to the function may allocate a lot of memory if you do not release the result list as soon as possible. So, best practice is : release the result list!

When inserting a template the Template-ID script of this template can decide to use another template instead. For more information see Description of panel 'Templates'.

Name Type Default Description
Return ItemList   Inserted frames must be deleted again with itemlist::release
pool DataPool - Datapool in which teh template is stored

0 : Use the current datapool
attribute String oder char* - Attribute name of the database table in which the template is stored

If attribute and table are empty, the default source for templates is used, you have to give only the template ID.
table_ String oder char* - Name of the database table in which the template is stored

If attribute and table are empty, the default source for templates is used, you have to give only the template ID.
ID int - ID under which the template is stored in the database
x float - Page relative position in points
y float - Page relative position in points
page int - Page number on which the template is to be located

-1 : Current page
layer String oder char* - Target layer on which the template is to be placed

0 or "" : deepest layer

Using InDesign® Server or comet_pdf the current front page is undefined!
id1, id2, id3, stringid int, int, int, String oder char* 0, 0, 0, "" Product Id of the object, linked against the template (used also for the Template-ID script, if any script is defined inside the given template). If id1 is 0, linking against the new object is suppressed.
autoLoad int 0 Link, load and build placeholders of the inserted frames automatically.

0 : No

1 : Yes, load and rebuild (if nesseccary) all inserted placeholders. Suppressed, if id1 = 0!
classID int 0 Do only deal with placeholders of the given class ID

0 : Ignore class ID. Link, load and build all placeholders
othwise : Do only link, load and build placeholders with the given class id.
addToCometGroup int 1 since Comet3.1 All frames of the template are grouped in one Comet group. make this group a sub groub of the current script frame.

1 : Yes
0 : No.
#include "internal/types.h"
#include "internal/products.h"

Add all entries of level two of selected product to the document. The entries must have their grid and element defined. 

#include "internal/text.h"
#include "internal/products.h"

int main ()
{
    ProductList		pl			= productlist::get ("selected [level = 2]");
    ItemList		inserted 	= 0;
    int				lastElem	= 0;
    int				grid, elem, pid;
    Product			p;
    float			left, top;
    int				pnum		= page::get (0);
    char			pname[1024];
    int				cc			= 0;
    float			ml, mt, mr, mb; 

    wlog ("", "# Starting import\n");
    progress::start ("Produktaufbau", productlist::length (pl));
    page::get_margins (pnum, &ml, &mt, &mr, &mb);

    for (p = productlist::first (pl); p; p = productlist::next (pl))
    {
        sprintf (pname, "Product %d [%s]", ++cc, product::gets (p, kStringID));
        wlog ("", "#  ---> Importing %s\n", pname);
        progress::step (pname, 1);

        pid	= product::get (p, kPageitemid);
        grid	= product::get (p, kGridid);
        elem	= product::get (p, kElementid);

        if (grid <= 0) grid = 2;

        //New page for each block of entries
        if (lastElem > elem)
        {
            page::create (1, pnum+1);
            pnum += 1;
        }
        lastElem = elem;

        left   = grid::left (grid, elem);
        top    = grid::top (grid, elem);

        inserted = document::place_items (
         	0, "", "", 
         	product::get (p,	kPageitemid),
         	left    + ml,
         	top    + mt,
         	pnum, "",
         	product::get (p,	kID),
         	product::get (p,	kID2),
         	product::get (p,	kID3),
         	product::gets (p,	kStringID),
         	1);

        if (inserted) itemlist::release (inserted);
        inserted = 0;
    }

    progress::stop ();
    return 0;
}

Version 1.1.7, January 2005 id1, id2, id3, stringid since version 1.4 R340, 8. May 2007 autoLoad, classID seit Version 1.4.2 R528, 17. Dez. 2007 addToCometGroup Version 3.1 R 1612, 21. Oct. 2009

priint:comet InDesign® Plug-Ins, comet_pdf

document::store_macro
document::place_indesign
pages
layer
URL[PYC:Document]{placeTemplate}

static ItemList document::place_snippet(
  int ID,
  float x = -1000.0,
  float y = -1000.0,
  int page = -1,
  char* layer = "",
  int id1 = 0,
  int id2 = 0,
  int id3 = 0,
  char* stringid = 0)

Insert a snippet into the given document.

The return value of the function is a new allocated itemlist (the list of imported frames). This list will released on the end of the script automatically. But looped calls to the function may allocate a lot of memory if you do not release the result list as soon as possible. So, best practice is : release the result list!

Name Type Default Description
ID int - Template ID, this parameter is reserved for future extensions of the snippet functionality and is currently unused
x float - Page relative position in points
y float - Page relative position in points
page int - Page number on which the snippet is to be located

-1 : Current page
layer String oder char* - Target layer on which the template is to be placed

0 or "" : deepest layer

Using InDesign® Server or comet_pdf the current front page is undefined!
id1 int - Id of the snippet to be inserted
id2, id3, stringid int, int, String oder char* 0, 0, "" Further object Ids. These parameters aure currently unused.

Version 4.1.7 R26766, April 2020

priint:comet InDesign® Plug-Ins, comet_pdf

document::place_items
document::place_indesign

static ItemList document::place_indesign(
  char* path,
  int srcPage,
  char* srcLayers,
  int cometGroup,
  int page,
  float x,
  float y,
  char* layer = "",
  int id1 = 0,
  int id2 = 0,
  int id3 = 0,
  char* stringid = 0,
  int autoLoad = 0,
  int classID = 0,
  int addToCometGroup = 1)

Import frames from a InDesign® document or snippet (inds or idml).

The return value of the function is a newly allocated itemlist (the list of imported frames). This list will be automatically be released at the end of the script. But looped calls to the function may allocate a lot of memory if you do not release the result list as soon as possible. So, best practice is : release the result list!

If you call the function from inside a load placeholder, you should take care to import the frames only once. You may use frame::remove_sub_cometgroups if the placeholder makes only one import.

Name Type Default Description
Return ItemList   Inserted frames must be deleted again with itemlist::release
path String or char* - Complete path to the document or snippet
⇨ Frames to import. Snippets will ignore these parameters, snippets are always imported completely.
srcPage int - Page number in document (1-based)

0 : Ignore page number and layer and use cometGroup
srcLayers String or char* - Blank delimited list of layers ("\"AAA\" \"BBB\"") : Import only frames from these layers.

"" : Visible layers only
cometGroup int - Import a comet group. Ignored if page is greater 0

0 : Ignore Comet groupt
⇨ Import destination
page int - destination page (1-based)
x float - Page relative position in points

-1000.0 : X position of original frame(s)
y float - Page relative position in points

-1000.0 : Y position of original frame(s)
layer String or char* "" Target layer on which the template is to be placed

"" : Current layer
⇨ Comet things
id1, id2, id3, stringid int, int, int, String or char* 0, 0, 0, "" Product Id of the object linked against the template (used also for the Template-ID script, if any script is defined inside the given template). If id1 is 0, linking against the new object is suppressed.
autoLoad int 0 Link, load and build placeholders of the inserted frames automatically.

0 : No
1 : Yes, load and rebuild (if nesseccary) all inserted frames. Suppressed, if id1 = 0!
classID int 0 Do only deal with placeholders of the given class ID

0 : Ignore class ID. Link, load and build all placeholders
othwise : Do only link, load and build placeholders with the given class id.
addToCometGroup int 1 since Comet3.1 All frames of the template are grouped in one Comet group. Make this group a sub groub of the current script frame.

1 : Yes
0 : No.

Import all frames from Layer 1 and 2 iof page 3. 

int main ()
{
    document::place_indesign (
     	"$DESKTOP/aaa.indd",
     	3, "\"Ebene 1\" \"Ebene 2\"",
     	0,
     	4, 100.0, 100.0);
    return 0;
}

Import all frames of the Comet group of a given product. To get the Comet group, the document must be opened and in th foreground. If the frame already imported frames, this frames will removed automatically before importing. 

char			stSrcDoc []		= "$DESKTOP/big.indd";

int main ()
{
    ItemRef		docRef		= document::get_front ();
    ItemRef		docRef2		= item::alloc ();
    int			mustClose	= 0;
    ItemRef		frameRef	= item::alloc ();
    int			groupID		= 0;

    if (!document::is_opened (stSrcDoc, docRef2))
    {
        item::release (docRef2);
        docRef2 = document::open (stSrcDoc);
        mustClose = 1;
    }
    document::select (docRef2);

    document::find_frame (frameRef, 3, 100, 10, 0);
    if (item::defined (frameRef))
    {
        groupID = frame::get_cometgroup (frameRef, 0);
    }
    if (groupID == 0)
    {
        if (mustClose) document::close (docRef2);
        showmessage ("Product not found!");
        return 0;
    }

    document::select (docRef);
    frame::remove_sub_cometgroups (gFrame);
    document::place_indesign (
     	stSrcDoc, 
     	0, "",
     	groupID,
     	2, 100.0, 100.0);

    if (mustClose) document::close (docRef2);

    return 0;
}

Version 2.1 R 1800, 14. March 2010

priint:comet InDesign® Plug-Ins

document::place_items
pages
layer

static int document::find_frame(
  ItemRef frameRef,
  int classid,
  int id,
  int id2,
  int id3,
  char* sid = "",
  int diveInto = 0)

Find the first frame which is linked with an object of a required class. For the result an ItemRef with reserved memory must be passed.

Name Type Default Description
frameRef ItemRef - The variable contains the frame after the search, test with item::defined
classid int - class ID no or 0
id int - Look for this product
id2 int - Look for this product
id3 int - Look for this product
sid String or char* "" StringID to search for. A product is only found when all 3 IDs and the StringID match. If no StringIDs are used, an empty value is used.
diveInto int 0 Search inside sub frames?

0 : no
1 : yes

Find the first frame which is linked with the shrub (1, 3, 4) 

ItemRef		frame	= item::alloc ();

document::find_frame (frame, 1, 1, 3, 4);
if (!item::defined (frame))
{
    item::release (frame);
    showmessage ("frame not found");
    return 1;
}

sid since Version 1.3 (Build 96)

priint:comet InDesign® Plug-Ins, comet_pdf

Parameter diveInto since v4.0.5 R11012

static int document::export_(
  ItemRef docRef,
  char* destPath,
  char* format,
  char* profile = "",
  int uiflag = 0,
  int fileflag = 1,
  ...)

Export a document in a specific target format.

Name Type Default Description
Return int   0 or ErrorCode

2201 : Document to pack not found
2202 : Error while creating package file
2203 : Cannot open file to package
2204 : Error while checking links of document (NOT missing images!)
2205 : Cannot create internal link object
2206 : Link resource not found
2207 : Error while duplicating image file
2208 : Error while updating link
docRef ItemRef - Document which is to be exported

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
destPath String or char* - Target path for the export. If the folder path does not exist, it will be automatically generated.
format String or char* - Target format. following case sensitiven specifications are possible:
  Format Comments
JPG JPEG
inx InDesign® exchange format  
idml InDesign® exchange format  
svg SVG Creates a file nameX.svg for each page > 1 which is automatically deleted with defined file flag.
svgz compressed SVG Creates a file nameX.svgz for each page > 1 which is automatically deleted with defined file flag.
swf Adobe Flash Multimedia Datei No longer supported from InDesign® 2020 onwards! In this case, the function returns error -2020.
xml XML  
pdf Adobe PDF To export a arbitrary pages or spreads please use pdf_export.
EPS EPS Creates a file name_X.EPS for each page which is automatically deleted with defined file flag.
package Package folder or zip

since v4.0.4 R9030 Create a package folder and optionally zip it.

Please note: The packaging of documents is done by the Javascript document.packageForPrint function built into InDesign®. Errors in function behavior or InDesign® crashes due to the function cannot be traced back to the cScript function document::export_, these are internal errors directly in InDesign®!

w2ml Comet interchange format since v4.1 R23572
profile String or char* "" Name of the configuration which is to be used for the export.Profile will only be used for the format "pdf" only:

interactive#[key:values;] : Interactive PDF with settings defined in the list of the Key-Value pairs

not empty : PDF (print) with the given profile

"" or 0 : PDF (Print) with the current PDF export options for PDF (Print)
uiflag int 0 0 : Suppress all dialogs and progess bars. Necessary export specifications are taken from the current or standard specifications of InDesign® or from the profile.
1 : Only the requisite dialogs will be displayed.
2 : All dialogs and progress bars will be displayed.
3 : with format "package" only Execute the menu command File -> Package .... For technical reasons, this function can only be executed at the next idle time of InDesign® but not directly when called in the script. Before using the function it is essential to check if this is possible and useful in your work flow!
fileflag int 1 Should the target file be overwritten?
0 : Do not overwrite the target file
1 : Target file may be overwritten
2 : only for format "package" Compress package folder to zip. If the package folder was created here, it is removed automatically again. (On the Mac, the folder is moved to the trash.)
⇨ Additional parameters (any number of key|value(s) pairs in any order).

since v3.3 R2580 25.07.2011 and CS4 SWF-Export. Missing values are taken (if available) from the SWF export dialog. The dialog settings are left untouched by calls to document::export (.., "swf", ...).

SWF export is no longer supported from InDesign® 2020 onwards!

since v4.0.4 R9030, 2. Oct. 2015 You may use the following pkg: options to configure packages (format "package").
"swf:generateHTML" int - 0 | 1
"swf:viewAfterExport" int - 0 | 1
"swf:sizeAndFitting:fitTo" int - 0: 1280x800
1 : 1240x620
2 : 1024x768
3 : 984x588
4 : 800x600
5 : 760x420
6 : 640x480
7 : 600x300
"swf:sizeAndFitting:scale" float - 0.0 -100.0
"swf:sizeAndFitting:size" float, float - Size in points
"swf:bkTransparent" int - since CS5

0 | 1
"swf:transparencyHandler" int - since CS5

0: ignore
1 : flatten
2 : native
"swf:mediaHandler" int - since CS5

0: Include All
1 : Appearance Only
"swf:pageTransition" int - 0 : Without

since CS5
1 : From document
2 : Blinds
3 : Box
4 : Combine
5 : Cover
6 : Dissolve
7 : Fade
8 : Page Turn
9 : Push
10 : Split
11 : Uncover
12 : Wipe
13 : Zoom In
14 : Zoom Out

versions prior CS5
All other values turning on page transitions
"swf:bookControl:curl" int - 0 | 1 - Interaktives Aufrollen der Seiten einschließen
"swf:bookControl:showAtRest" int - 0 | 1
"swf:bookControl:cornerTease" int - 0 | 1
"swf:bookControl:sizePercent" float - 0.0 - 100.0
"swf:frameRate" int - since CS5

frames per second
"swf:textExport" int - 0 : Live text
1 : Rasterize
2 : Vectorize
3 : Vellum
"swf:rasterizePage" int - 0 | 1
"swf:rasterCompression" int - 0 : JPEG
1 : PNG
2 : Automatic
"swf:jpgQuality" int - 0 : Minimum
1 : Low
2 : Medium
3 : High
5 : Maximum
"swf:rasterResolution" int - resolution (ppi)
"swf:curveQuality" int -  
"swf:resampling" int - 0 : off
1 : Average
2 : Subsample
3 : Bikubic
"swf:resampleTreshold" int -  
"swf:readerSpreads" int - 0 | 1
"swf:useNetwork" int - 0 | 1
"swf:includePreloader" int - since CS5

0 | 1
"pkg:fonts" int 1 Export fonts?

0 : No
1 : Yes
"pkg:images" int 1 Export images?

0 : No
1 : Yes. In this case, all references inside the package are updated too.

Missing images do NOT lead errors. Links to missing images are left untouched and a log message is written.
"pkg:profiles" int 1 Export color profiles?

0 : No
1 : Yes
"pkg:hiddenLayers" int 1 Export colors and fonts from hidden layers?

0 : No
1 : Yes
"pkg:ignoreErrors" int 1 Ignore preflight errors?

0 : No
1 : Yes
"pkg:report" int 1 Write a report?

0 : No
1 : Yes
"pkg:idml" int 0 Available since InDesign® CC, ignored in prio versions. Add an IDML of the document to the package?

> 0 : No
1 : Yes
"pkg:pdf" int 0 Available since InDesign® CC, ignored in prio versions. Add PDF of the document to the package?

> 0 : No
1 : Yes
"pkg:pdfstyle" String or char* 0 Available since InDesign® CC, ignored in prior versions. Style for creating the PDF. Take care, it's a String!

Export the current document in a PDF file. The profile 'Paul' must be set up (Menu; file:PDF-Export specifications:Define ...). 

int main ()
{
    int       result	= 0;

    result = document::export_ (
     	0,
     	"/AAA/BBB/a.pdf",
     	"pdf",
     	"Paul",
     	0,
     	1);
    return 0;
}

Make a zip package from the current document. Do not export color profiles and do not write a report. 

result = document::export_ (0, "", "package", "", 0, 2, 
 	"pkg:profiles", 0,
 	"pkg:report", 0);

Version 1.1.4
uiflag = 3 seit v4.1.7 R27305, 20. Jul 2020

priint:comet InDesign® Plug-Ins

document::open
document::close
document::duplicate
document::print
document::pdf_export
comet.CDocument.exportPDF

static int document::pdf_export(
  ItemRef docRef,
  char* destPath,
  char* profile = "",
  int scope = 2,
  List indexes = 0,
  ...)

PDF export of document pages or spreads in any order.

Since v4.1 R23334 The function can export all Comet notes into the created PDF. To do so, simply add 4 (for visible notes) or 8 (for visible and hidden notes) to the parameter scope of of the function. Please note the installations hints for the support of PDF comments.

This function can also be used to create interactive PDFs. Since it is not possible to store profiles for interactive PDFs, the export options can be made in the script call. To create interactive PDFs, define the profile parameter as follows

interactive#{key:value;} with key and value according to the following table.

If the list of key-values is empty, the current InDesign® settings are used to export interactive PDFs. If at least one value is defined, the values specified in the table in bold type are used as defaults.

Key Value Description
General singlePages no | 0
yes | 1 		Pages : Generate separate PDF Files

Available since InDesign® 2020
singlePagesSuffix beliebiger String Pages : Generate separate PDF Files Suffix

Only when creating separate pages (singlePages:yes;)

Available since InDesign® 2020
magnification actual
fitPage
fitWidth
fitHeight
fitVisible
25
50
75
100 		Viewing : View
pageLayout single
singleContinue
twoUp
twoUpContinue
twoUpCover
twoUpCoverContinue 		Viewing : Layout
fullScreen no | 0
yes | 1 		Viewing : Open in Full Screen Mode
flipPages no | 0
yes | 1 		Viewing : Flip Pages

The specification is used only in full screen mode (fullScreen:yes;).
flipSpeed Seconds as integer, Default 5 Viewing : Flip Pages Every ... seconds

The specification is used only in full screen mode (fullScreen:yes;).
transition nothing
blend
combine
box
cover
push
uncover
wipe
zoomIn
zoomOut
disolve
fade
turn
split 		Viewing : Page Transition

The specification is used only in full screen mode (fullScreen:yes;).
autoShow no | 0
yes | 1 		Viewing : View After Exporting
showInteractives no | 0 - Appearance Only
yes | 1 - Include All 		Options : Forms and Media/td>
thumbnails no | 0
yes | 1 		Options : Embed Page Thumbnails
layers no | 0
yes | 1 		Options : Create Acrobat Layers
tags no | 0
yes | 1 		Options : Create Tagged PDF
tabs definition | 0
structure 		Options : Use Structure for Tag Order

For tagged PDFs only (tags:yes;)
Compression compression jpeg
lossless
auto
 Compression
quality min
low
medium
high
max
 JPEG Quality
resolution PPI as integer
Minimum 10
Default 72 		Resolution (ppi)
Advanced title document
file
 Accessibility Options : Display Title
language String Accessibility Options : Language

For the available languages and their spelling, please refer to popup menu Accessibility Options : Language.
Security The security settings depend very much on the used PDF viewer. Viewers like Acrobat or Acrobat Pro may not be able to display all the security settings you have made. If the settings are missing, please check first whether you can create settings manually!
password String
Default: no password 		Document Open Password
authorization String
Default: no password 		Permissions : Permissions Password
allowPrint no | 0
low
yes | 1
 Permissions : Print Allowed

Only active if an authorization password is set (authorization:'pwd';)
allowAssembly yes | 1
no | 0 		Changes Allowed -> Inserting, deleting and rotating pages

Only active if an authorization password is set (authorization:'pwd';)
allowFormfill yes | 1
no | 0 		Changes Allowed -> Fill in form fields and signing

Only active if an authorization password is set (authorization:'pwd';)
allowNotes yes | 1
no | 0 		Changes Allowed -> Commenting

Only active if an authorization password is set (authorization:'pwd';)
allowExtraction yes | 1
no | 0 		Changes Allowed -> Any except extracting pages

Only active if an authorization password is set (authorization:'pwd';)
allowCopy yes | 1
no | 0 		Enable copying of text, images and other content

Only active if an authorization password is set (authorization:'pwd';)
allowChange yes | 1
no | 0 		Enable text access of screen reader devices

Only active if an authorization password is set (authorization:'pwd';)
plainTextForMeta yes | 1
no | 0 		Enable plaintext metadata

Only active if an authorization password is set (authorization:'pwd';)

The specification with comet-options ... at the end of the PDF profile name can be used to define specific settings, that are not supported by the standard PDF export. At present, ‘only’ the conversion of letters to paths is supported:

Key Value Description
outlines no | 0
yes | 1 		Convert all texts to paths. The conversion of the individual letters in the InDesign document into paths is done temporarily for the export and is rolled back again after the export. There is no comparable function for comet_pdf.

Use the current settings for the PDF export and create a PDF in which all letters are replaced by paths.

Parameter profile : "with comet-options outlines:yes"

Use the basic profile for the PDF export and create a PDF in which all letters are replaced by paths.

Parameter profile "[Basic Style] with comet-options outlines:yes"

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front) 0 : current script or front document
destPath String or char* - complete path and name for the destination

0 or "" : use path and name (with extension .pdf) of the document. (not working on new unsaved documents)
profile String or char* "" Name of PDF export profiles

interactive# : Interactive PDF with the current settings of the PDF export for interactive PDFs

interactive#[key:values;] : Interactive PDF with settings defined in the list of the Key-Value pairs

not empty : PDF with the given profile

"" or 0 : PDF with the current PDF export options for PDF (Print)

Endung "with comet-options ..." : Export-Erweiterungen, siehe hier
scope int 2 Export pages or spreads?
1 : spreads
2 : pages

Export of Comet notes:
+4 : Export visible Comet notes only\
+8 : Export all Comet notes

See document::notes::set_pdf_prefs for defualt settings. In comet_pdf there is no visibility of notes, therfores always all notes exported here.

Never use PDFs with Comet notes as to be the final print version!

If the document does not contain Comet notes that need to be exported, the PDF is left unchanged - or, in other words, a recompositions of the document is not needed in this case.

Ignored by Illustrator.
indexes List 0 List of 0-based page or spread numbers. If 0, the following numbers are used. If no numbers follow, all pages/spreads are exported.

To place PDF comments on their right sides, pages must be complete and in the right order in case of exporting Comet notes.

Ignored by Illustrator.
... int, ... - Any number of 0-based page or spread numbers, only used if indexes is 0.

To place PDF comments on their right sides, pages must be complete and in the right order in case of exporting Comet notes.

Ignored by Illustrator.

PDF export of various document pages. Pay particular attention to complete page ranges when exporting Comet notes (scope + 8). 

int main ()
{
    document::pdf_export (0, "$DESKTOP/aaa/aaa_spreads.pdf", "", 1, 0);
    document::pdf_export (0, "$DESKTOP/aaa/aaa_spread_2_4.pdf", "", 1, 0, 2, 4);
    document::pdf_export (0, "$DESKTOP/aaa/aaa3.pdf", "", 2, 0, 3);
    document::pdf_export (0, "$DESKTOP/aaa/aaa1401.pdf", "", 2, 0, 1, 4, 0, 1);
    document::pdf_export (0, "$DESKTOP/aaa/aaa1702.pdf", "", 2, 0, 1, 7, 0, 2);

    return 0;
}

Export all odd pages of the current document to a PDF. 

int main()
{
    List  pnums = list::alloc ();
    int   p;

    for (p = 0; p < document::pages (); p += 2)
    {
        list::append (pnums, p);
    }

    document::pdf_export (0, "$DESKTOP/aaa.pdf", "", 2, pnums);

    return 0;
}

Export of Comet notes since v4.1 R23334, 28. Jun 2018 Version 3.2 R 2234, 24. Dec. 2010

priint:comet InDesign® Plug-Ins, Illustrator

document::export_
document::print
document::notes::set_pdf_prefs
document::notes::import
comet.CDocument.exportPDF

static int document::html_export(
  ItemRef docRef = 0,
  char* destPath = "",
  int target = 1,
  ItemRef itemToExport = 0,
  ...)

HTML export of a document or parts of a document.

Name Type Default Description
Return int   0 or ErrorCode

-8000 : Export script not found. See InDesign® subfolder Scripts/Export As XHTML
-8001 : No objects to export
-8002 : Error while exporting
-8003 : Linked image not found
-8004 : Linked image out of date
-8005 : Cannot export embedded images (Image skipped)
-8006 : Linked movie not found
-8007 : Skipped unsupported movie(s) - only SWF is suppoerted..
docRef ItemRef 0 Document to export (from)

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
destPath String or char* "" Complete path for html file. Any existing file will be overridden.
"" : Use path and name of the document (with extension .html)
int target 1 What to export?

0 : current selection
1 : complete document
2 : following object (itemToExport)
itemToExport ItemRef 0 Valid frame or table reference. If given, docRef is ignored
⇨ Export option. Any number of key/value pairs. Keys are given as strings ("gifPalette" for instance). Values are depending on their keys, see below.
"bulletListPolicy" int 0 0 : regular unordered list items
1 : convert bullets to text
"numberedListPolicy" int 0 0 : regular ordered list items
1 : fixed list items
2 : convert to text
"imageHandling" int 0 0 : Copy original
1 : optimized

2 : link with server path
"serverImgPath" String or char* "" server path
$DESKTOP, ... are not replaced here!
"serverImgExtension" String or char* "" image extension (e.g. ".jpg")
"imageConversion" int -1 image conversion
-1 : use current setting
0 : automatic
1 : JPEG
1 : GIF
"gifpalette" int -1 Color panel for GIF
-1 : use current setting
0 : Flexibel (no dithering)
1 : System (Mac)
2 : Web
3 : System (Windows)
"gifInterlaced" int -1 Interlace?
-1 : use current setting
0 : no
1 : yes
"jpegQuality" int -1 image quality
-1 : use current setting
0 : low
1 : medium
2 : high
3 : maximal
"jpegFormat" int -1 format methode for jpeg
-1 : use current setting
0 : profgressive encoding
1 : base line
"styleHandling" int 0 CSS options
0 : empty CCS class declarations
1 : no CSS
2. external CSS file
"styleSheet" String or char* "" complete path/URL to style file
$DESKTOP, ... are not replaced here!
"linkToJavaScript" int 0 link with external JavaScript file?
0 : no
1 : yes
"javaScriptURL" String or char* "" complete path/URL to JavaScript file
$DESKTOP, ... are not replaced here!
"showErrors" int -1 Show errors?
0 : no
1 : yes

Export the complete current document. 

int main ()
{
    int 	r;

    r = document::html_export (0, "", 1, 0, "showErrors", 1);
    wlog ("", "#html export : %d\n", r);

    return 0;
}

Export the current script frame 

int main ()
{
    int 	r;

    r = document::html_export (0, "", 2, gFrame);
    wlog ("", "#html export : %d\n", r);

    return 0;
}

Export of a table. 

int main ()
{
    int 		r;
    Table		T	= table::alloc ();

    table::get (T, 0, 0);

    r = document::html_export (0, "", 2, T, "styleHandling", 2, "styleSheet", "/Users/paul/Desktop/xxx.css");
    wlog ("", "#html export : %d\n", r);

    return 0;
}

Version 3.1 R 1819, 22.3.2010

priint:comet InDesign® Plug-Ins

static int document::jpeg(
  ItemRef docRef,
  char* destPath,
  char* destName,
  int aggregateSpreads,
  float resolution,
  float bleed,
  float greekBelow,
  int quality,
  int suppressNonPrintableFrames = 0)

Export all spreads or pages to jpeg.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Target document

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
destPath String or char* - Destination folder, if an empty string is supplied the document folder will be used
destName String or char* - Name of JPEG files (without extension). If an empty string is supplied the document name will be used
aggregateSpreads int - 0: export pages, 1: export spreads
resolution float 72.0 resolution in dpi
bleed float 0.0 bleed amount
greekBelow float 7.0 below which size (in dpi) should text be greeked?
quality int - Various parameters. Valid settings are:

Antialiasing for all objects: kAntiAliasing

Full resolution graphics: kFullResGraphics

Draw gray: kDrawGray

Transparency:
 kXPOff
 kXPLow
 kXPMedium
 kXPHigh
 kXPMaximum

JPEG Quality (The setting effects only to the quality of the saved file, not of the preview itself!):
 kJPEGLowQuality
 kJPEGGoodQuality
 kJPEGExcellentQuality
 kJPEGGreatQuality

JPEG Encoding (The setting effects only to the quality of the saved file, not of the preview itself!):
 kJPEGBaseline
 kJPEGProgressive

quality can be supplied as a bitfield (kXXX... + kXXX + ...). The default value is:
kAntiAliasing + kFullResGraphics + kXPHigh + kJPEGExcellentQuality + kJPEGBaseline
suppressNonPrintableFrames int 0 Visibility of non-printable frames

0 Non-printable frames are visible
1 Non-printable frames are NOT in the image
#include "internal/types.h"

Version 2.1 R989, 21. October 2008
Parameter suppressNonPrintableFrames seit v4.0.5 R14478, 12. Jan 2017

priint:comet InDesign® Plug-Ins

document::export_

static int document::duplicate(
  ItemRef docRef,
  char* destPath,
  int fileflag = 1)

Copy a document in a new file.

Name Type Default Description
Return int   0 oder ErrorCode
docRef ItemRef - Document which is to be duplicated

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
destPath String or char* - Target path for the export. If the folder path does not exist, it will be automatically created.
fileflag int 1 Should the target file be overwritten?
0 : Do not overwrite the target file
1 : Target file may be overwritten

Version 1.1.4
document::open
document::close
document::export_
comet.CDocument.saveAsCopy

priint:comet InDesign® Plug-Ins
Illustrator


static int document::force_redraw(ItemRef docRef = 0, int doAll = 0)

Force redrawing of the document window. The command can be used to redraw all documents, a single document or only the given document. The command is useful in tasks in which changes to the document are to be shown directly when the script is executed. If only individual texts or text parts are to be re-rendered, you can use the textmodel::force_redraw function.

Using comet_pdf the call has no effect of course.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef 0 Document

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
doAll int 0 0 : Update the given document window only

1 : Update all document windows. The parameter docRef is not taken into account in this case.

v4.2 R33733, 3. Nov 2023

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator
textmodel::force_redraw
comet.CDocument.redraw

static int document::print(
  ItemRef docRef,
  char* profile,
  char* path = "",
  int uiflag = 0,
  int fileflag = 1)

Printing a document. The document can optionally be sent to a printer or stored as Postscript file. The specifications of the print settings are defined using the details of the print instructions (Menu; Datei:Druckvorgaben).

Name Type Default Description
Return int   0 oder ErrorCode
docRef ItemRef - Document which is to be printed

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
profile String or char* - Print presettings. The specification is case sensitive. See InDesign® menu; File:Print styles
Empty string : use the current settings of the print dialog
path String or char* "" Empty : print of file query
Otherwise : Printer output as Postscript file. The path to the specific file will be created automatically.
uiflag int 0 0 : Display all dialogs and progress bars
1 : Do not display progress bars
2 : Warnings are not displayed
4 : Print end-dialog is not displayed
8 : File selection dialog not displayed
0xFF : Nothing displayed The options may be linked with logical OR (|).
fileflag int 1 Should the target file be overwritten?
0 : Do not overwrite the target file
1 : Target file may be overwritten

Create a Postscript file from the current file, without displaying any dialogs or progress bars. 

document::print (0, "", "/AAA/KKK/GGG/asdd.ps", 0xff);

Version 1.1.4

priint:comet InDesign® Plug-Ins

document::export_

static int document::move_pageitems(
  ItemRef docRef,
  int startPage,
  int pages,
  int deleteOld = 1,
  float leftpages_offset_x = 0.0,
  float leftpages_offset_y = 0.0,
  float rightpages_offset_x = 0.0,
  float rightpages_offset_y = 0.0)

Reposition the contents of document pages. The contents of the pages can then be positioned using a page-specific offset. If not otherwise specified, the contents of the first target page will be deleted.

Name Type Default Description
Return int   0 or error code
docRef Item - Target document

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
startPage int - 1-based page number from which the contents are to be repositioned.
0 : Page of the first selected frame or the current text selection
-1 : Currently displayed page of the document
pages int - Number of pages by which the contents are to be moved
<0 : Move frames backwards to the beginning of the document
0 : No frame movings
>0 : Move frames forward towards the end of the document
deleteOld int 1 Should the contents of the first target page be deleted?
1 : Delete
0 : Do not delete
The parameter is only valid for the first page. The following pages are already empty because of the repositioning of their contents.
leftpages_offset_x float 0.0 If a frame is repositioned from a right or unisex page to a left page , then the frame is repositioned to the left/right on the new page by the specified offset. If the frame was already on the left page, then no offset will be inserted.
leftpages_offset_y float 0.0 see above, repositioning above or below
rightpages_offset_x float 0.0 If a frame is repositioned from a left or unisex page to a right page , then the frame is repositioned to the left/right on the new page by the specified offset. If the frame was already on the right page, no offset is inserted.
rightpages_offset_y float 0.0 see above, reposition below/above

Verschiebe ab Seite 3 alle Dokumentrahmen um zwei Seiten nach hinten. 

main ()
{
    document::move_pageitems (
     	0,	// front document
     	3,	// from page 3 ...
     	2,	// two pages back
     	1,	// Last page of doc. before deleting.
     	11.0, 22.0,
     	33.0, 44.0);
}

v3.0

priint:comet InDesign® Plug-Ins

static int document::build_products(
  char* statement = "watched",
  int flags = 0,
  char* errmess = 0,
  ItemRef baseFrame = 0,
  int removeFrame = 0,
  int pageNum = -1,
  char* layerName = "",
  char* defaultMasterpage = "",
  int gridID = 0,
  int pageitemID = 0,
  int anchor = 0,
  float left = 0.0,
  float top = 0.0,
  float right = 0.0,
  float bottom = 0.0,
  int purgeSequence = 0,
  char* sequName = "",
  int preScript = kNoRule)

omet3-Product Build-Up. This function is one of the most powerfull of the complete Comet Plugin. All or selected products of the product panel are assumed to the current document. For the positioning all product-specific grid spaces are used. If a product does not have a grid space, a standard grid may be used. The stored specifications of the product are inputted; if these specifications do not exist, a standard specification can be used. During the input care must be taken to ensure that the specifications are not added on top of existing page contents. New pages are automatically set up. The parent page, used for this purpose, can likewise be stored for the product or defined as a standard. Parent page elements are not automatically localised. For the localisation of parent page items on the newly create pages, use the function page::masteritems_load.

The function supports #include "internal/types.h"

Three different algorithms can be used for the import :
Description New pages Document customisation Flags
grid-orientated
Search in the grid for the next free raster space with the following characteristics
  • still no document content at this position
  • new frames can still be added to the pages (with flag kUseFullPage or kUseBleed) or fitting the bounding box around all current grid places (without flag kUseFullPage or kUseBleed)
  • bei kCheckGridElementSize, if the new frames fit the grid space
 Each time the last grid space is reached or if the page is full. As the parent page defaultMasterpage is used (or asked prior to import). Yes. All frames behind the inserted or deleted products are assigned new grid spaces according to the current general positioning information. This feature can be switched off using kDisableOptimizing. kUseDefaultGrid

Optional
  • kDisableOptimizing
  • kUseFullPage/kUseBleed
  • kCheckGridElementSize
  • kCheckIfNotExists
  • kShowErrors
grid-fixed
Use a standard grid. The products will be inserted into the next grid space in each case regardless of the pre-existing document frames. If the positioning info of a product contains a template, this template will be used for importing, otherwise the template defined in pageitemID is used. If even pageitemID is not present, it will be inquired prior to import.		 Each time upon reaching the last grid space. As a parent page defaultMasterpage is used (or inquired prior to the import). No kUseDefaultGrid + kIntersectionsAllowed

Optional
  • kIgnoreIncompletePlacements
  • kCheckIfNotExists
  • kShowErrors
product-defined
Use the positioning instructions in the respective products.		 Is always then defined, when the target space is already occupied in the document. It is used in the specified parent pages in the product. If it is not defined, defaultMasterpage is used (or inquired prior to import). No kIntersectionsAllowed

Optional
  • kIgnoreIncompletePlacements
  • kAllowIncompletePlacements
  • kCheckIfNotExists
  • kShowErrors
The flag kAllowIncompletePlacements can lead to unexpected results. In this case where there is incomplete positioning info the assigned or inquired standard values are used and processed with these import options, meaning the next free grid space is used and existing page content is overlayed.

Prior to building the products, a preparatory script can be executed (Parameter preScript). This script is particular used to post-process the lists of the products to be built. The script is executed after the list of the products to be imported has been compiled.

The script is defined like all other scripts in the database table actions resp. in the XML file actions.xml. It must have the class number 14 (= support script for the product build). For the management of product positionings and pages breaks in these scripts see All about "page breaks".

For more details about the scripts see here.

Before and after the (complete) build-up of each product, a script can be executed with which you can change the page element for the next product 'at the last second'. In the flowchart of the productlist::establish, these scripts (highlighted in yellow) are called PreRule resp. PostRule.

The script are defined like all other scripts in the database table actions resp. in the XML file actions.xml and must have the class number 14 (= support script for the product build). For the management of product positionings, pages breaks in these scripts see All about "page breaks".

For more details about the scripts see here.

To activate the script, set the value of kPreRuleid resp. kPostRuleid of the according product to the ID of the script. 

product::set (p, kPreRuleid, 3020);

Name Type Default Description
Return int   0 or ErrorCode. For an exact error description the function can be assigned an allocated string for the error description, see parameter errmess.
statement String or char* "watched" Selection of objects (and sub-objects), which are to be built, see here.
flags int 0 Import control. The value is given as the sum (byte field) of the following constants; as an example kUseDefaultGrid + kUseFullPage. There are three different import algorithms, for more see the table above.

kUseDefaultGrid : Ignore the grid information stored in the products and use the standard grid (see parameter grid).

kIgnoreIncompletePlacements : Products with incomplete information on positioning (grie and/or tempate) are not added to the document.

kAllowIncompletePlacements : If the product positionings are to be used (kUseDefaultGrid in off status), it is ascertained prior to the import, if all the information is complete. If this byte is defined, incomplete information is authorised and the standard specifications used.

kCheckIfNotExists : Check before inserting if the product is already planned within the document, if yes, it will no longer be inserted.

kIntersectionsAllowed : When inserting the products with a standard grid a check is made to ensure no pre-existing page contents are overlapped and the the new product also fits the page. The check can be interrupted using the kIntersectionsAllowed flag because then the next empty grid space is automatically used. (s.a. kUseFullPage, kCheckGridElementSize

kCheckGridElementSize : From the grid spaces normally only the positions are used. Using the flag a check can additionally be made to see if the new frames also fit into the grid space. Only active if overlapping is not permitted (kIntersectionsAllowed not switched on).

kUseFullPage : When testing the pre-existing page contents, a check is also made to see of the new product actually fits the bounding box around all current grid places. With the flag it can be stipulated that the current page including the page margins may be used. Only active if intersections are not permitted (kIntersectionsAllowed not switched on).

kUseBleed : like kUseFullPage, but the bleed is added to the page size

kPreferDefaultPageItem : Use template pageitemID for all products to insert and ignore the templates given in the products.

kShowErrors : Errors that arise are automatically shown in an error dialog.
errmess String or char* 0 If the variable identifies an allocated string (e.g. of type char[256] or type String), an error message can be received here.
⇨With the following information the start page and the layer for the import are specified.
baseFrame ItemRef 0 The page and the layer in which the frame is located in the document will be used as the start position for the import. If the information is empty, this information will be ascertained from pageNum and layerName.
removeFrame int 0 Should the start frame be removed from the document? 0 : No, keep frame
otherwise : delete frame
pageNum int -1 1-based page number, after which the insert is to be made. The value will only then be used if baseFrame is = 0.
-1 : Use the current page

Using InDesign® Server or comet_pdf the current front page is undefined!
layerName String or char* - Name of the target layer for the import. The value is only then used, if baseFrame is = 0.
0 or "" : Current layer
⇨Information on standard grid, template and parent page. The values will only be used if the flag kUseDefaultGrid is activated or if the flag kAllowIncompletePlacements is activated and a product to be inserted does not have complete positioning information.
Prior to the insert of the product, it is ascertained if at least one product requires the standard value. If yes, a check is made if all standard values have been assumed by the function. If at least one of this values is missing, a dialog is automatically opened, which inquires the missing values.
defaultMasterpage String or char* 0 Name of the parent page which should be used if new pages must be inserted into the document. If in one-page documents different parent pages are to be used for left and right pages, both parent page names are stated within simple quotation marks and divided by a comma comma.
Example 1 : "A parent page"
Example 2 : "'A parentpage left', ''A parentpage right'"
gridID int 0 Standard grid. For inserting, the sequence of the storing positions (sorted according to ID) of the grids will be used.
pageitemID int 0 Standard template for inserting products. If a product contains information different from that of the template , this template will be used. In doing so it will be ensured that the template fits the target page type and where requireda an alternative template may be selected, for more see Description of the panel 'Templates'.
anchor int 0 Blocked page areas. The specification is only valid for the start page of the import, all successive pages are of course newly set up and are empty. For the comparison limits the frame baseFrame is used. If this information is empty, the limits can be given in the following parameters left, ....
-1 : Open dialog for request 0 : Use complete page for inserting 1 : Begin below the frame
2 : Begin alongside the frame
3 : Inserts can be made under and alongside the frame
⇨Specifications on positioning on the start page. The specifications are only valid for the start page and only for objects that are inserted with the standard grid. It can be determined if inserts may first be made alongside and/or belown the specified frame. In this cases only those grid spaces are selected whose frames does not intersect the specified frame.
left float 0.0 When using the standard grid it must be ascertained which of the grid spaces should first be used. This is determined using a page frame and an anchor position. left determines the left page of the frame.
top float 0.0 ... top page of the frame
right float 0.0 ... right page of the frame
bottom float 0.0 ... bottom page of the frame
purgeSequence int 0 Process products each in its own sequence

0 - Whole assembly in a sequence. The assembly can be reversed with an undo. For larger imports, the import will frequently be interrupted by a dialog which issues an unhelpful message stating that the sequence is too large, and therefore cannot be reversed.
1 - Every product will be processed in its own purged sequence (see purge_sequence). Using Undo each product will be removed individually from the document. With "clean" the parameter has no meaning.
sequName String or char* "Building %d. Produkt" Name of the individual import sequence, is only used where purgeSequence != 0. The specification must contain exactly one %d, which is substituted by the current import counter, i.e. "Import %d. Product" for example. If the specification is empty, the default string will be used.
preScript int kNoRule ID of the preparation script. The script is executed in that the list of the products to be imported is determined and can then be used to process the product list. For more see product::set, product::clone, productlist and on chapter Script support.

kNoRule - No script is executed
Sonst ID des Skriptes, Skriptaufbau siehe hier.
#include "internal/types.h"
#include "internal/products.h"

Assemble in the document using a panel script all products which are eye-marked, which have a higher-layer product. 

#include "internal/types.h"

int main ()
{
    char		errmess[512];
    int			result;

    if (gRun != 1) 	return 0;

    result = document::build_products (
     	"watched id2 > 0",// Only eye-marked products
     	kAllowIncompletePlacements,
     	errmess,		// Error report

     	// Target page and layer. Is gFrame defined,
     	// Page numbers and layers will be ignored
     	gFrame,			
     	true,			// Delete frames
     	-1,				// page number
     	"",				// layer

     	// Placement notice
     	// If one of the values is not defined then
     	// a dialog will be opened, and the value
     	// is queried.
     	"A-Musterseite",// Parent page
     	2,				// Grid ID
     	1,				// Template ID
     	0);				// Anchor (undef = -1)

    if (result && result != -1199)
     	showmessage ("%d : %s", result, errmess);

    return 0;
}

To assemble all products with a higher-layer product, which can be read from the list, only the statement above must be changed. 

list id2 > 0 and layer = 1

And to demonstrate how short the instruction can be, here again without commentary. 

int main ()
{
    char		errmess[512];
    int			result;

    if (gRun != 1) return 0;

    result = document::build_products (
     	"watched id2 gt; 0",
     	kAllowIncompletePlacements,
     	errmess);

    if (result && result != -1199)	showmessage ("%d : %s", result, errmess);

    return 0;
}

Version 1.2.1 (19. August 2005)
firstPageType since Version 1.3.1, R115

priint:comet InDesign® Plug-Ins

datapool::get_products
page::masteritems_load

static int document::get_firstpagetype(ItemRef docRef = 0)

Determine if the first document page is a left, middle or right page. The command only returns a result for one-page documents, otherwise a 1 will always be returned.

Name Type Default Description
Return int   kLeftPage (0) : left page
kRightPage (2) : right page
1 : no or two-page document
docRef ItemRef 0 Dokument, the type of first page of which is to be determined

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
#include "internal/types.h"

Version 1.3.1 (19. Januar 2006)

priint:comet InDesign® Plug-Ins, comet_pdf

document::build_products
document::place_items
document::set_firstpagetype

static int document::set_firstpagetype(int typ, ItemRef docRef = 0)

Define whether the first page of the document is a left or right page. The determination of the first page type only applies to one-page documents. The page type is required in order to determine the page type of a given document.

Name Type Default Description
Return int   0 or ErrorCode
typ int - kLeftPage (0) : left page
kRightPage (2) : right page
docRef ItemRef 0 Document, where the first page type is to be changed

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
#include "internal/types.h"

Version 1.3.1 (19 January 2006)

priint:comet InDesign® Plug-Ins, comet_pdf

document::get_firstpagetype
document::build_products
document::place_items

static int document::split(
  ItemRef docRef = 0,
  char* postfix = "",
  char* basename = "",
  char* destPath = "")

Split a document into its pages. Every document contains all parent pages, styles, colors and so on. Left pages stay left pags, rigt pages stay right pages.

Existing page document in the destination folder are overridden!

Name Type Default Description
Return int   errro code or 0
docRef ItemRef 0 Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
postfix String or char* "" The names of the page documents consists of a postfix and the page number, for instance myfile_1.indd, myfile_2.indd, ... . In this example "_" is the postfix.
basename String or char* "" Base name of page documents

"" : Use name of source document
destPath String or char* "" Destination folder for the page documents. If the folder doesn't exist, it will cretaed.

"" : Folder of source document

Version 1.3.3 (P/R 59)

priint:comet InDesign® Plug-Ins

document::concat

static int document::concat(char* dest, char* src)

Concatanation of one document to another. All pages of the second document will append to the destinations document. Parent pages, styles, colors and so on are not imported.

Addings pages to a document may change their spread order! Magnets between pages of different spreads are deleted.

Visible Comet note are relinked to their current destinations. Invisible notes are ignored!

Name Type Default Description
Return int   0 or ErrorCode
dest String or char* - Full path of document to append on. Doesn't matter, if this file opened already!

"" : front document
src String or char* - Full path of file to append

Version 1.3.3 (P/R 59)

priint:comet InDesign® Plug-Ins

document::split

static int (
  char* firstPath,
  char* newname = "",
  char* destpath = "",
  long lastPage = -1)

DEPRECATED! Please use the functions file::get_nth and document::concat instead.

Name Type Default Description
Return int   -1198

Please use the functions file::get_nth and document::concat instead.

static int document::allow_shuffle(ItemRef docRef = 0, int allow = 1)

Allow or disable page shuffling in a document.

Name Type Default Description
Return int   Error Code or 0
docRef ItemRef 0 Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
allow int 1 Allow shuffle on/off 1 : Allow
0 : Disable

Version 1.4 (R 334), 11. Apr. 2007

priint:comet InDesign® Plug-Ins

static int document::justify_text(
  ItemRef docRef,
  int page,
  char layerName,
  int keepLast,
  char* style1,
  ...)

Vertical justification.

Name Type Default Description
Return int   errro code or 0
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
page int - 1-based doc page. Apply the function only to frames on this page

-1 : all pages If a text chain contains frames on other pages too, the function is applied to the frames on this pages too!
layerName String or char* - Apply function on frames on the given layer

"" : all layers
"--visible--" : visible layers only
"--active--" : active layer only
otherwise : valid layer name
keepLast int - 1 : Leave the last frame of a text chain untouched

0 : Can change the last frame too
style1, percent1, ... String or char*, float, ... - List of paragraph style names and percentages (float). With the percentage you can determine, how much space is occupied for justification by this style. The sum of all values may not exceed 100.0 percent.

0 or "" : Wildcard for "any" style

Here you can find a (german) test document 

 

Version 1.4 (R 339), 2. Mai 2007

priint:comet InDesign® Plug-Ins

document::justify_text_reset
textmodel::justify

static int document::justify_text_reset(
  ItemRef docRef,
  int page,
  char* layerName,
  int keepLast,
  char* style1,
  ...)

Reset vertical justification.

Name Type Default Description
Return int   errro code or 0
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
page int - 1-based doc page. Apply the function only to frames on this page

-1 : all pages
layerName String or char* - Apply function on frames on the given layer

"" : all layers
"--visible--" : visible layers only
"--active--" : active layer only
otherwise : valid layer name
keepLast int - 1 : Leave the last frame of a text chain untouched

0 : Can change the last frame too
style1, ... String or char*, ... - List of paragraph styles to reset to the style definition

Here you can find a (german) test document 

 

Version 1.4 (R 339), 2. Mai 2007

priint:comet InDesign® Plug-Ins

document::justify_text
textmodel::justify_reset

static int document::remove_redundant_tags(
  ItemRef docRef = 0,
  int page = -1,
  char* layerName = "")

Clean up textplaceholders. Text attribute changes such as font, textsize, color, ... are breaking the Comet placeholders into several so called runs. The Comet plug ins are runs save. But for templates and document templates it would be a good idea, to remove this redundant information for performance reasons.

Using the application menu Plug Ins:Placeholder:Remove redundant placeholders before save users can remove redundant placeholders automatically.

This function removes all redundant placeholder runs from the document. You're able to shrink the selection to a given page and/or layer, but is recommended to remove redundant runs from the entire document.

Name Type Default Description
Return int   errro code or 0
docRef ItemRef 0 Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
page int -1 1-based doc page. Apply the function only to frames on this page

-1 : all pages
layerName String or char* "" Apply function on frames on the given layer

"" : all layers
"--visible--" : visible layers only
"--active--" : active layer only
otherwise : valid layer name

Version 1.4.1 R417, 24. Jul 2007

priint:comet InDesign® Plug-Ins

textmodel::remove_redundant_tags
textmodel::gremove_redundant_tags
frame::remove_redundant_tags

static int document::table_of_content(
  ItemRef frameRef,
  char* styleName,
  int update_all = 1)

Insert or update table(s) of content (TOC). In case an overset in any text of the document, a warning dialog asks if we should include table of content entries in overset. In fact, the include overset flag is set in runtime through user's input(a warning dialog). Currently, the function is only used for scripting to control the default behavior if we should include overset or not.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Destination frame

!= 0 : Insert or update a TOC (in) this frameIf the frame isn't a text frame, it is converted to a text frame. Any existing text in the frame will be deleted.

0 : Update all TOCs of the given name styleName existing inside the front document (set update_all to 1 in this case)
styleName String or char* "" Name of an existing TOC style

"" : Use the documents default TOC style
update_all int 1 If the document contains some more TOCs of the given style, what do you prefer?

1 : update these TOCs too
0 : leave these TOCs untouched

Replace the content of the current script frames with the TOC named "My content". TOCs with the same name probably inside the the document are left untouched. 

int main ()
{
    int 		res;

    res = document::table_of_content (gFrame, "My content", 0);
    wlog ("", "# table_of_content returns %s\n", serror (res));

    return 0;
}

Version 1.4.2 R491, 26. Oct 2007

priint:comet InDesign® Plug-Ins

static int document::adapt_many(char* xmlControlFile = 0)

Apply page adaptions for the front document. The destination sizes are give in an XML file. If the given path is empty, a file dialog is invoked. You must have the PageAdapter plug-in installed and licensed to run the function.

Name Type Default Description
Return int   errro code or 0
xmlControlFile String or char* "" complete path to the control file

"" : file dialog

The example shows a valid control file. The following formats are defined : A3, A4, A5, B5, CD, US-Letter, US-Long, Tabloid, US-Letter Half, US-Long Half. 

<?xml version="1.0" encoding="utf-8"?>
<adaptions
 	basename 	= ""
 	folder 		= "$DESKTOP/adapt/ok"
 	errfolder 	= "$DESKTOP/adapt/err">
 	<adaption>
 		<format>A4</format>
 		<width></width>
 		<height></height>
 		<name></name>
 	</adaption>
 	<adaption>
 		<format>A5</format>
 		<width></width>
 		<height></height>
 		<name></name>
 	</adaption>
 	<adaption>
 		<format>A3</format>
 		<width></width>
 		<height></height>
 		<name></name>
 	</adaption>
</adaptions>

Version 1.4.2, R 504, 12. Nov. 2007

priint:comet InDesign® Plug-Ins

document::adapt

static int document::adapt(
  float width,
  float height,
  char* destPath = 0,
  char* destName = 0)

Create one adaption of the current document. You must have the PageAdapter plug-in installed and licensed to run the function.

Name Type Default Description
Return int   0 or ErrorCode
width, height float - Size of the new document in points.
destPath String or char* "" Destination folder

"" : Use the current doc path
destName String or char* "" Name of new doc (without the extender .indd)

"" : Use the current doc name plus "_wxh"

AppleScript to adapt a document 

tell application "Adobe InDesign® CS5"
 	set d to document 1
 	tell d
 		adapt width 333.3 height 444.4
 	end tell
end tell

Version 1.4.2, R 504, 12. Nov. 2007

priint:comet InDesign® Plug-Ins

document::adapt_many

static int document::adapt_self(float width, float height)

Create one adoption of the current document. You must have the PageAdapter plug-in installed and licensed to run the function.

Name Type Default Description
Return int   0 or ErrorCode
width, height float - Size of the new document in points.

Version 2.1, R 1090, 17. Dez. 2008

priint:comet InDesign® Plug-Ins

document::adapt
document::resize

static int document::start_stamping(
  int actionID,
  ItemRef origin,
  ItemList designated = 0,
  int autoClose = 0)

Starts the 'Stamping' of frames. Stamping is the term used to describe a process that starts from an first frame, the so-called origin and does 'something' to the frames that are subsequently clicked. The stamping action can be arbitrary and can refer to the number of clicked frames and/or to the original frame.

Stamping actions can only be started from the Front Row panel!

Due to an InDesign bug, stamp actions can unfortunately not be undone as one step at the moment. Therefore, to undo the actions, unfortunately, a corresponding number of undos must be made. We will correct this behavior as soon as possible - but this is not up to us alone.

Stamp scripts must be introduced with the following pragma in exactly this notation: 

#pragma _stamp_

Stamping is divided into three steps:

  1. Start : document::start_stamping
  2. Apply Stamp : This action can be executed as often as you like.
  3. Finish : Automatically or by document::stop_stamping

Usually, all three steps can be implemented in one script. Based on the existence of global variables (see below) you can use declared to distinguish whether the stamping should be started or executed. In all cases the stamping must be terminated either automatically or with document::stop_stamping function. To finish the stamping the counter gCounter or e.g. the CMD key (system::cmdkey) are suitable.

Stamping can be restricted to any number of frames by the designated list. In this case clicks on other frames will be ignored and stamping can be aborted automatically when the last frame has been processed. To do this, set the autoClose parameter to the value 1.

If a frame list is specified, all involved frames will be marked with a corresponding red sequence number when the stamping process starts. The new sequence numbers assigned when clicking are displayed in blue behind the old numbering.Do show the sequence numbers the Nails and Magnets must be visible (menu Document Context -> Nails and Magnets -> Show). Here is a screenshot:

To correct the already assigned stamp order, simply click in a frame that is already highlighted in blue. The sequence and the counter \span[src]{gCounter will then automatically reste to this frame and all frames with a higher blue number will have their blue number taken away again.

Without or with empty frame list no sequence numbers are shown.

The following global variables are defined when performing the stamp actions in steps 2 and 3 (but not in step 1).
Name; Type Description
gCounter int*

0-based counting number of the stamp. The variable is a pointer, So you can change the count number in the script. To get its conent, use *gCounter.

gOriginalFrame ItemRef The first frame of the stamping action passed in in the parameter origin of document::start_stamping.

Name Type Default Description
Return int   0 : No error and continue
1 : Cancel stamping
actionID int - ID of the action to be performed.

-1 : Current script
origin ItemRef - Original (first) frame. Usually this is the current script frame gFrame.
designated ItemList 0 List of frames that can be stamped. The list should contain the origin frame. The frames will have a sequence number circled in red in the order of the list.

0 : All frames may be edited. In this case, the frames do not receive sequence numbers.
autoClose int 0 Do you want stamping to end automatically?

1 : Yes. Stamping will automatically stop when the gCounter counter reaches the length of the designated list. If the designated list is empty, the option is ignored. Note : By incrementing the counter or with a return value > 0 you can end the stamping stamp independent of this option earlier.

otherwise : Do not end automatically

The script takes the color of the first frame and decreases the amount of green in all subsequent frames by 20. Here is a before/after screenshot where stamping was started in the green frame and then the blue frames were clicked in sequence.

#pragma _stamp_

#include "internal/types.h"
#include "internal/text.h"

int main ()
{
    float	c1, c2, c3, c4;

    if (system::cmdkey ())
    {
        document::stop_stamping ();
        beep ();
        return 1;
    }

    if (!declared ("gCounter"))
    {
        document::start_stamping (-1, gFrame);
        return 0;
    }

    if (*gCounter > 0)
    {
        frame::get_color (gOriginalFrame, 0, 0, &c1, &c2, &c3, &c4);
        frame::color_rgb (gFrame, (int)(c1), (int)(c2) - (20 * *gCounter), (int)(c3));
    }

    return 0;
}

The next example is a bit more complex: All frames of the current page (or for left pages all frames of the spread) which contain a certain placeholder (in the example the placeholder 10) are searched. The found frames are sorted page by page by their placeholder prefix (which in this case should contain a number). With this frame list the stamping is started. With every click into a frame of this list the placeholder now gets t he current sequence number (plus 1, because it is 0-based!) as prefix. If the last frame is reached, the stamping is finished automatically. 

#pragma _stamp_

/*
	@@ICONID	533
	@@SEQ		1
	@@LABEL		Leitziffern
	@@HELP		Your Help Text
*/

#include "internal/types.h"
#include "internal/text.h"

//***************************************************************************

int stPlaceholderID	= 10;

//***************************************************************************

// Sort all links by their prefixes
//
int sort_links (Link a, Link b)
{
    int		result	= 0;
    int		pga	= page::get (link::frame (a));
    int		pgb	= page::get (link::frame (b));
    String	prea	= string::alloc ();
    String	preb	= string::alloc ();

    if (pga == pgb)
    {
        link::prefix (a, prea);
        link::prefix (b, preb);
        if (string::compare (preb, prea) < 0) result = 1;
    }
    else
    {
        if (pgb < pga)	result = 1;
    }

    string::release (prea);
    string::release (preb);
    return result;
}

//***************************************************************************

// Get all frames of the page
// If we are on a left page, also add the frames of the right page.
//
ItemList get_frames (ItemRef fr)
{
    int 			pg 			= page::get (fr);
    ItemList		pageFrames 	= itemlist::pageframes (pg, 1);
    ItemList 		pageFrames2	= 0;
    LinkList		lli			= linklist::alloc (0);
    Link			li;
    ItemRef			lif;

    itemlist::sort (pageFrames, kSortRowwise);
    if (pg % 2 == 0)
    {
        pageFrames2 = itemlist::pageframes (pg + 1, 1);
        itemlist::sort (pageFrames2, kSortRowwise);
        itemlist::appendlist (pageFrames, pageFrames2);
        itemlist::release (pageFrames2);
    }

    linklist::collect_any (lli, pageFrames, "--list--", kFirstIgnore, kSortNo, stPlaceholderID);
    linklist::sort (lli, sort_links);
    itemlist::clear (pageFrames);
    li 	= linklist::first (lli);

    while (li)
    {
        lif	= link::frame (li);
        if (itemlist::get_pos (pageFrames, lif) < 0)
        {
            itemlist::append (pageFrames, lif);
        }
        li = linklist::next (lli);
    }
    linklist::release (lli);

    return pageFrames;
}

//***************************************************************************

int find_placeholder (ItemRef fr, int pid)
{
    int 		result	= -1;
    int 		pos		= 0;
    int 		len, phid;

    while (pos < textmodel::fulllength (fr))
    {
        len = 0;
        textmodel::get_placeholder (fr, pos, &pos, &len, &phid);
        if (len > 0)
        {
            if (phid == pid)
            {
                result = pos;
                break;
            }
            pos = pos + len;
        }
        else
        {
            pos = pos + 1;
        }
    }

    return result;
}

//***************************************************************************

// Main function
//
int main ()
{
    char 		txt [512];
    ItemList	pageFrames 	= 0;
    int			pos;

    /span[c-comment]{// Emergency exit}
    if (system::cmdkey ())
    {
        document::stop_stamping ();
        wlog ("", "# Stamping Finished\n");
        beep ();
        return 1;
    }

    if (!declared ("gCounter"))
    {
        pageFrames = get_frames (gFrame);
        document::start_stamping (-1, gFrame, pageFrames, 1);
        itemlist::release (pageFrames);
        wlog ("", "# Start stamping\n");
        return 0;
    }

    pos = find_placeholder (gFrame, stPlaceholderID);
    if (pos < 0) return 0;

    sprintf (txt, "%d | ", *gCounter + 1);

    placeholder::change_tags (gFrame, 0, "Prefix+Apply", txt, kTextPlaceholder, pos, 1);
    placeholder::load (gFrame, 0, pos, 1);

    return 0;
}

v4.2 R30710, 11. May 2022

priint:comet InDesign® Plug-Ins

document::stop_stamping

static int document::stop_stamping()

Finish stamping frames.

Name Type Default Description
Return int   0 or ErrorCode

v4.2 R30710, 11. Mai 2022

priint:comet InDesign® Plug-Ins

document::start_stamping

static int document::resize(float width, float height)

Resize the current document.

Name Type Default Description
Return int   0 or ErrorCode
width, height float - new size of the new document in points.

Version 2.1, R 1090, 17. Dez. 2008

priint:comet InDesign® Plug-Ins

document::adapt_self

static int document::getid(
  ItemRef docRef,
  int* id1,
  int* id2 = 0,
  int* id3 = 0,
  char* stringid = 0)

Get the Comet id of a document.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
id1 int* - Variable for the ID1 of the document ID
id2 int* 0 Variable for the ID2 of the document ID, null allowed
id3 int* 0 Variable for the ID3 of the document ID, null allowed
stringid String or char* 0 Variable for the StringID of the document ID, null allowed

Version 1.4.2 R 565, 12. Jan. 2008

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

document::setid
comet.CDocument.getID

static int document::setid(
  ItemRef docRef,
  int id1,
  int id2 = 0,
  int id3 = 0,
  char* stringid = 0)

Set the Comet id of a document. ID1 of a document must not be <0!

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
id1 int - Value for ID1 of the document ID
id2 int 0 Value for ID2 of the document ID
id3 int 0 Value for ID3 of the document ID
stringid String or char* 0 Value for StringID of the document ID

Version 1.4.2 R 565, 12. Jan. 2008

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

document::setid
comet.CDocument.setID

static ItemRef document::get_book(ItemRef docRef = 0)

Get the book of a document. The book must must be opened in InDesign® .

Name Type Default Description
Return ItemRef   New allocated reference to the open book. You must release this result before a next call to the function using item::release

0 : No book found or open or no document opened
docRef ItemRef 0 Document to find the book for

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)

Get the book of the current document and write all siblings of the book to the logfile. 

int main ()
{
    ItemRef		book	= document::get_book (0);
    int			i;

    if (book::is_valid (book))
    {
        for (i = 0; i < book::count_docs (book); i++)
        {
            wlog ("", "%d. document : '%s'\n", i+1, book::nth_doc (book, i));
        }
    }

    item::release (book);
    return 0;
}

Version 2.1 R668, 9. April 2008

priint:comet InDesign® Plug-Ins

book
item
comet.CDocument.getBook

static int document::update_crossrefs(
  ItemRef docRef = 0,
  ItemList frames = 0,
  int updateCrossrefs = 1,
  int showProgress = 0)

Update all cross reference placeholders of a given document. If the book is part of an opened book, all documents of this book are updated too.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef 0 document to update all cross reference placeholders

span[keyword]{gDocument} or 0 : Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
frames ItemList 0 Update only placeholders of the given frames. In this case, the docRef is ignored.
updateCrossrefs int 1 Updating cross reference placeholders?

0 : No. Only affected, if the given document is part of a book. In this case the book is repaginated only.

1 : Only if the document is part of an opened book. In this case, all documents of the book are updated too.

2 : In single documents too.
showProgress int 0 Show progress while updating cross reference placeholders?
0 : No
1 : Yes

Version 2.1 R668, 10. April 2008

priint:comet InDesign® Plug-Ins

document::get_book

static int document::get_bleed(
  ItemRef docRef,
  int pageNum,
  float* inner,
  float* top,
  float* outer,
  float* bottom,
  int* isUniform)

Get current document bleed.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
pageNum int - 1- based page number. The page is needed, because the bleed is given for inner and outer edges (not left and right)

-2 : Get bleed without page checking
-1 : current front page

Using InDesign® Server or comet_pdf the current front page is undefined!

Ignored by Illustrator.
inner, top, outer, bottom float* - output variables (All values are given in points.)
isUniform int* - Use the same bleed for all edges?

Version 2.1 R1130, 22. Januar 2009

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

document::set_bleed
document::get_slug
comet.CDocument.getBleed

static int document::get_slug(
  ItemRef docRef,
  int pageNum,
  float* inner,
  float* top,
  float* outer,
  float* bottom,
  int* isUniform)

Get current document slug.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
pageNum int - 1- based page number. The page is needed, because the bleed is given for inner and outer edges (not left and right)

-2 : Get bleed without page checking
-1 : current front page

Using InDesign® Server or comet_pdf the current front page is undefined!
inner, top, outer, bottom float* - output variables (All values are given in points.)
isUniform int* - Use the same slug for all edges?

Version 2.1 R1130, 22. Januar 2009

priint:comet InDesign® Plug-Ins, comet_pdf

document::get_bleed
document::set_slug

static int document::set_bleed(
  ItemRef docRef,
  float inner,
  float top,
  float outer,
  float bottom)

Change the document bleed. Changing the bleed of a document will cause InDesign® to change the documents pasteboard size!

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
inner float - New value for the inner bleed (in points). If top, outer and bottom are missed, this value is used for all the other edges too.
top, outer, bottom float see above  

Version 2.1 R1130, 22. Januar 2009

priint:comet InDesign® Plug-Ins, comet_pdf

document::get_bleed
set_slug
comet.CDocument.setBleed

static int document::set_slug(
  ItemRef docRef,
  float inner,
  float top,
  float outer,
  float bottom)

Change the document slug. Changing the slug of a document will cause InDesign® to change the documents pasteboard size!

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
inner float - New value for the inner slug (in points). If top, outer and bottom are missing, this value is used for all the other edges too.
top, outer, bottom float see above  

Version 2.1 R1130, 22. Januar 2009

priint:comet InDesign® Plug-Ins, comet_pdf

document::get_slug
document::set_bleed

static int document::get_pasteboard_gutter(
  ItemRef docRef,
  float* minXBorder,
  float* minYBorder)

Get the documents pasteboard borders.

Name Type Default Description
Return int   0 or ErrorCode

pasteBoardDocErr (1272) : CS versions prior CS5
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
minXBorder float* - return the minimum value for left and right border.
minYBorder float* - return the minimum value for top and bottom border.

v3.3.1 R4100, 1. Aug 2013 and CS5

priint:comet InDesign® Plug-Ins

document::set_pasteboard_gutter

static int document::set_pasteboard_gutter(
  ItemRef docRef,
  float minXBorder,
  float minYBorder)

Set the documents pasteboard borders.

The paste board size is limited by exsiting frames automatically. At least on boarder of a frame remains visible.

Name Type Default Description
Return int   0 or ErrorCode

pasteBoardDocErr (1272) : CS versions prior CS5
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
minXBorder float - new minimum value for left and right border.

-1.0 : Do not change
-10.0 : Default (595.276 Pt, InDesign® preferences for this value are ignored.)
minYBorder float - new minimum value for top and bottom border.

-1.0 : Do not change
-10.0 : Default (72.0 Pt, InDesign® preferences for this value are ignored.)

v3.3.1 R4100, 1. Aug 2013 and CS5

priint:comet InDesign® Plug-Ins

document::get_pasteboard_gutter

static int document::show_page_elements(ItemRef docRef, int state)

Show or hide the page elements linked with any document page.

Page elements are never shown in prints nor PDFs. Changes made by this function are only visible in InDesign® Desktop, but still committed to the document by InDesign® Server and comet_pdf aswell. With comet_pdf you can export page elements to PDFs using the option -ae.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
state int -1 State

-1 : Toggle
0 : Hide
1 : Show

Version 3.0 R1155, 2. Feb. 2009

priint:comet InDesign® Plug-Ins, comet_pdf

document::page_elements_shown

static int document::page_elements_shown(ItemRef docRef = 0)

Are Page elements currently shown in the document?

Name Type Default Description
Return int   0 : invisible (or error)
1 : visible
docRef ItemRef 0 Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)

Version 3.0 R1155, 2. Feb. 2009

priint:comet InDesign® Plug-Ins, comet_pdf

document::show_page_elements

static int document::export_notes(
  ItemRef docRef = 0,
  char* destPath = 0,
  String destString = 0,
  int flags = 4)

See document::notes::export_

document::notes::export_

static int document::import_notes(
  ItemRef docRef = 0,
  char* srcPath = 0,
  String srcString = 0,
  int flags = 6)

See document::notes::import

document::notes::import

static int document::show_notes(ItemRef docRef = 0)

See document::notes::show

document::notes::show

static int document::hide_notes(ItemRef docRef = 0)

See document::notes::hide

document::notes::hide

static int document::set_default_style(
  ItemRef docRef,
  int type,
  char* stylePath)

Set the current default paragraph or text style. Styles are set document dependent.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
type int - type of style?

1 : paragraph style
2 : text style
stylePath String or char* - Name (or ':' delimited path) of style to use as the new documents default

Get the current default paragraph style and then set a new one. 

int main ()
{
    char		oldStyle [256];
    int			res;

    *oldStyle = 0;
    document::get_default_style (0, 1, oldStyle);
    showmessage ("Old default style : '%s'.", oldStyle);

    res = document::set_default_style (0, 1, "Beta:Geuze");
    if (res)	showmessage ("Cannot set default style.");

    return 0;
}

Version 2.1 R 1582, 5. Okt. 2009

priint:comet InDesign® Plug-Ins

document::get_default_style
textmodel::insert

static char* document::get_default_style(
  ItemRef docRef,
  int type,
  char* stylePath)

Get the current default paragraph or text style. Styles are set document dependent.

Name Type Default Description
Return String or char*   (Depends on parameter stylePath) A pointer to stylePath
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
type int - type of style?

1 : paragraph style
2 : text style
stylePath String or char* - Name of style (or complete, ':' delimited style path)

Get the current default style and change it. 

int main ()
{
    char			oldStyle [256];
    int			res;

    *oldStyle = 0;
    document::get_default_style (0, 1, oldStyle);
    showmessage ("Old default style : '%s'.", oldStyle);

    res = document::set_default_style (0, 1, "Beta:Geuze");
    if (res)	showmessage ("Cannot set default style.");

    return 0;
}

Version 2.1 R 1582, 5. Okt. 2009

priint:comet InDesign® Plug-Ins

document::get_default_style
textmodel::insert

static int document::set_modified(ItemRef docRef = 0, int modified = 0)

Set the modified-state of a document. The function does not change the document itself.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef 0 Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
modified int 0 state of the document

0 : document not modified
1 : document modified

Suppress saving a possible changed document. 

int main ()
{
    document::set_modified ();
    return 0;
}

Version 2.1 R1978, 27.06.2010

priint:comet InDesign® Plug-Ins

static int document::get_modified(ItemRef docRef = 0)

Get the modified-state of a document.

Name Type Default Description
Return int   0 (not modified), 1 (modified) or ErrorCode
docRef ItemRef 0 Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)

Exclude unsaved documents from processing. 

int main ()
{
    if (document::get_modified ())
    {
        return 0;
    }

    // further processing
    // ...

    return 0;
}

Version 3.3 R2764, 14.12.2011

priint:comet InDesign® Plug-Ins, Illustrator

static int document::set_units(
  ItemRef docRef = 0,
  int horiz_unit = 0,
  int vert_unit = 0,
  int text_units = 0,
  int text_size_units = 0,
  int print_units = 0,
  int line_units = 0,
  float customHPoints = -1.0,
  float customVPoints = -1.0,
  float key_nudge = -1.0,
  float ppi = -1.0)

Set document measurement units.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
horiz_unit, horiz_unit int 0 horizontal/verctical unit

0, kUnitUndefined: leave unchanged
kUnitPoints
kUnitPicas
kUnitInches
kUnitInchesDecimal
kUnitMillimeters
kUnitCentimeters
kUnitCentimeters
kUnitCiceros
kUnitAgates (ab CS5)
kUnitPixels (ab CS5)
text_units int 0 Units for (??)

0, kUnitUndefined: leave unchanged
kUnitPoints
kUnitPixels (ab CS5)
text_size_units int 0 Units for text size

0, kUnitUndefined: leave unchanged
kUnitPoints
kUnitPixels (ab CS5)
print_units int 0 Units for printing

0, kUnitUndefined: leave unchanged
kUnitPoints
kUnitMillimeters
kUnitPixels (ab CS5)
line_units int 0 Units for 'Contour'

0, kUnitUndefined: leave unchanged
kUnitPoints
kUnitMillimeters
kUnitPixels (ab CS5)
customHPoints, customVPoints float -1.0 custom points for horz/vert ruler - What ever that means.

-1.0 leave unchanged otherwise : value in points
key_nudge float -1.0 keyboard nudge increment

-1.0 leave unchanged otherwise : value in points
ppi float -1.0 Point/Inch

-1.0 leave unchanged otherwise : value in points
#include "internal/types.h"
#include "internal/types.h"

int w_unit (char * m, int u)
{
    char			ustr[512];

    if (u == kUnitUndefined)			strcpy (ustr, "Unit undefined");	
    else if (u == kUnitPoints)			strcpy (ustr, "points");	
    else if (u == kUnitPicas)			strcpy (ustr, "picas");	
    else if (u == kUnitInches)			strcpy (ustr, "inches");	
    else if (u == kUnitInchesDecimal)	strcpy (ustr, "decimal inches");	
    else if (u == kUnitMillimeters)		strcpy (ustr, "mm");	
    else if (u == kUnitCentimeters)		strcpy (ustr, "cm");	
    else if (u == kUnitCiceros)			strcpy (ustr, "ciceros");	
    else if (u == kUnitAgates)			strcpy (ustr, "agates");	
    else if (u == kUnitPixels)			strcpy (ustr, "pixels");

    if (m)	 wlog ("", "# %s	: ", m);
    wlog ("", "%s\n", ustr);
    return 0;	
}

int w_units (ItemRef docRef)
{
    float					h, v, nudge, ppi;

    w_unit ("Horizontal", 	document::get_units (docRef, kHorizontalUnit));
    w_unit ("Vertical", 	document::get_units (docRef, kVerticalUnit));
    w_unit ("Text", 		document::get_units (docRef, kTextUnit));
    w_unit ("Textsize", 	document::get_units (docRef, kTextSizeUnit));
    w_unit ("Print", 		document::get_units (docRef, kPrintUnit));
    w_unit ("Line", 		document::get_units (docRef, kLineUnit));

    h 	= document::get_custompoints (docRef, kHorizontalUnit);
    v 	= document::get_custompoints (docRef, kVerticalUnit);
    nudge	= document::get_keynudge_inc (docRef);
    ppi	= document::get_ppi (docRef);

    wlog ("", "Pointsize [%f, %f], key nudge %f, ppi %f\n", h, v, nudge, ppi);

    return 0;
}

int main ()
{
    float					h, v, nudge, ppi;

    wlog ("", "=== Before ===\n");
    w_units (0);

    document::set_units (
     	0,
     		kUnitPixels,		// horiz
     		kUnitAgates,		// vert
     		kUnitPixels,		// text	pt/px
     		kUnitPixels,		// textsize	pt/px
     		kUnitMillimeters,	// print	pt/px/mm
     		kUnitMillimeters,	// lines	pt/px/mm
     		18.0, 22.0,
     		2.3456,
     		120.0);

    wlog ("", "=== After ===\n");
    w_units (0);

    return 0;
}

Version 3.1 R2187, 25. Okt. 2010

priint:comet InDesign® Plug-Ins

document::get_units
document::get_custompoints
document::get_keynudge_inc
document::get_ppi

static int document::get_units(ItemRef docRef = 0, int what = 0)

Get a document unit.

Name Type Default Description
Return int   0 or
kUnitPoints
kUnitPicas
kUnitInches
kUnitInchesDecimal
kUnitMillimeters
kUnitCentimeters
kUnitCentimeters
kUnitCiceros
kUnitAgates (ab CS5)
kUnitPixels (ab CS5)
docRef ItemRef 0 Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
what int kHorizontalUnit Unit to retreive:

kHorizontalUnit
kVerticalUnit
kTextUnit unit for '??'
kTextSizeUnit unit for 'text sizes'
kPrintUnit unit for 'print'
kLineUnit unit for 'contour'
#include "internal/types.h"

Version 3.1 R2187, 25. Okt. 2010

priint:comet InDesign® Plug-Ins

document::set_units
document::get_custompoints
document::get_keynudge_inc
document::get_ppi

static float document::get_custompoints(ItemRef docRef = 0, int what = 0)

InDesign® -API documentation : "custom points for horz/vert ruler".

Name Type Default Description
Return float   Current value in points or 0.0 in case of an error
docRef ItemRef 0 Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
what int kHorizontalUnit Value to retreive:

kHorizontalUnit
kVerticalUnit
#include "internal/types.h"

Version 3.1 R2187, 25. Okt. 2010

priint:comet InDesign® Plug-Ins

document::set_units
document::get_units
document::get_keynudge_inc
document::get_ppi

static float document::get_keynudge_inc(ItemRef docRef = 0)

Keyboard nudge increment.

Name Type Default Description
Return float   Current value in points or 0.0 in case of an error
docRef ItemRef 0 Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)

Version 3.1 R2187, 25. Okt. 2010

priint:comet InDesign® Plug-Ins

document::set_units
document::get_units
document::get_custompoints
document::get_ppi

static float document::get_ppi(ItemRef docRef = 0)

Pixel/Points for the document.

Name Type Default Description
Return float   Current value in points or 0.0 in case of an error
docRef ItemRef 0 Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)

Version 3.1 R2187, 25. Okt. 2010

priint:comet InDesign® Plug-Ins

document::set_units
document::get_units
document::get_custompoints
document::get_keynudge_inc

static int document::get_visible_areas(
  ItemRef docRef,
  int page,
  int flags,
  List pageNums,
  List cometGroupIDs,
  IDTypeList ids,
  RectList bboxes,
  FloatList visible_sizes,
  FloatList sizes,
  FloatList percents)

Calculate the visibles areas of Comet groups. The visible area of a frame is the intersection of the following areas :

As you can imagine easily, the procedure for calculating intersections and sizes of arbitrary shapes is very complex. To solve the integrals of the curve pieces (Bézier curves), some interpolations are used. This may cause an average error of 0.03 per thousand (150 times less than the allowed alcohol in alcohol-free beer).

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
page int - page number

-1 : all pages
otherwise : 1-based page number
flags int - Control the calculation

kUseClippath : In case of images, use the intersection of the current image clip path and the frame shape instead of the frame shape alone. Paths may be arbitrarily complex.

kAllowHoles : Normaly holes in images are counted to the image size. You may turn off this behavior by using the kAllowHoles flag. The option is valid only if kUseClippath is active.

kCheckTransparenz : As described above, frame transparency is ignored for overlappings. Using image clip path stands in contradiction to this assumption because the whole background is treated as transparent area. Using kCheckTransparenz, the clip path is used only if the frame has
  • no background color
  • blend mode is not "normal"
  • Oopacity is less than 100.0
The option is valid only if kUseClippath is active.

kUseMargins : Only visible parts of frames are counted. Frame parts in the paste board are ignored. If the flag kUseMargins is set, the visible background area is shrinked to page of the frame without the page margins.
⇨ The following lists are filled on successful return (and may be 0) with one entry for every Comet group. All lists are of same length (instead of 0 values of course).
pageNums List - 1-based page number
cometGroupIDs List - Comet group-ID
ids IDTypeList - Object id of Comet group or frame
bboxes RectList - Comet group/frame bounding box
visible_sizes FloatList - Visible size of Comet group/frame in square points
sizes FloatList - Size of bounding box in square points
percent FloatList - percentage of page used (0.0 - 100.0), see kUseMargins).
#include "internal/types.h"
#include "internal/types.h"

int write_areas (
 	List			pageNums,
 	List			cometGroups,
 	IDTypeList		ids,
 	RectList		bboxes,
 	FloatList		visible_sizes,
 	FloatList		sizes,
 	FloatList		percents)
{
    int				i	= 0;
    int				p	= -1;
    int				p1;
    IDType			id;
    Rect			r;

    if (list::length (pageNums) == 0)
    {
        wlog ("", "document::calc_areas : No frames found\n");
        return 0;
    }

    for (i = 0; i < list::length (pageNums); i++)
    {
        // Pagenum
        p1 = list::get (pageNums, i);
        if (p1 != p)	 wlog ("", "Page %d\n", p1);
        p = p1;

        // Comet group
        wlog ("", "	Comet group %d\n", list::get (cometGroups, i));

        // Id
        id = idtypelist::get (ids, i);
        wlog ("", "	Id [%d, %d, %d, '%s']\n", idtype::id (id), idtype::id2 (id), idtype::id3 (id), idtype::stringid (id));

        // BBoxes
        r	= rectlist::get (bboxes, i);
        wlog ("", "		bbox %f %f %f %f\n", rect::left (r), rect::top (r), rect::right (r), rect::bottom (r));

        // Areas
        wlog ("", "		Netto	: %f\n", floatlist::get (visible_sizes, i));
        wlog ("", "		Brutto	: %f\n", floatlist::get (sizes, i));
        wlog ("", "		Percent	: %f\n", floatlist::get (percents, i));

    }

    return 0;
}

int main ()
{
    int				flags			= kUseClippath + kUseMargins;
    List			pageNums		= list::alloc ();
    List			cometGroups		= list::alloc ();
    IDTypeList		ids				= idtypelist::alloc ();
    RectList		bboxes			= rectlist::alloc ();
    FloatList		visible_sizes	= floatlist::alloc ();
    FloatList		sizes			= floatlist::alloc ();
    FloatList		percents		= floatlist::alloc ();

    document::get_visible_areas (0, -1, flags, pageNums, cometGroups, ids, bboxes, visible_sizes, sizes, percents);
    write_areas (pageNums, cometGroups, ids, bboxes, visible_sizes, sizes, percents);

    return 0;
}

Version 3.2 R2210, 2. Dez. 2010

priint:comet InDesign® Plug-Ins

frame::get_visible_area
rectlist
floatlist
rect
idtype
idtypelist

static int document::get_links(
  ItemRef docRef,
  int page,
  char* layer,
  ItemList resultList)

Get document links.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef 0 Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
page int -1 Page number (1-based). Only links at the given page are retreived.

≤0 : all pages
Otherwise : 1-based page number
layer String or char* "" Layer name. Only links at the given layer are retrieved.

"" : All layers
Otherwise : layer name
resultList ItemList - Allocated result list.

Using InDesign® the list entries are not document frames. To use the entries, use the functions of the frame::doclink module.

Using comet_pdf the result list contains the actual document frames which can also be used in all other frame functions.

Write the document links into the log file. 

int main ()
{
    ItemList	lks	= itemlist::alloc ();
    ItemRef		lk	= item::alloc ();
    ItemRef		fr	= item::alloc ();
    char		p	[5000];
    int			i;

    document::get_links (0, 0, "", lks);
    for (i = 0; i < itemlist::length (lks); i++)
    {
        itemlist::get (lks, lk, i);

        frame::doclink::get_frame (lk, fr);
        frame::doclink::get_path (lk, p);

        wlog ("", "Frame %d\t<- %d [%d, '%s']\n",
         	item::getint (fr),
         	item::getint (lk),
         	frame::doclink::get_state (lk), p);
    }

    return 0;
}

v3.3 R2550, 30.06.2011
Support for comet_pdf since v4.2 R32078, 28. Dec 2022

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CDocument.getDocLinks

static int document::update_links(
  ItemRef docRef = 0,
  int page = 0,
  char* layer = "",
  IDTypeList changedLinks = 0)

Update (the) links of the document. You may update the links of a given page and/or layer only. A result list can contain the updated frames and the paths of their links.

Using comet_pdf the function is available but has no effect and the result list remains empty always.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef 0 Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
page int -1 Page number. Only links at the given page are updated.

-1 : all pages
otherwise : 1-based page number
layer String or char* "" Layer name. Only links at the given layer are updated.

"" : All layers
otherwise : layer name
changedLinks IDTypeList 0 list of changed links. idtype::id will return the UID of the updated frame of the list entries (On text chains the first frame of the chain). idtype::stringid will return the complete path of the link of the list entries. 
int main ()
{
    IDTypeList		updated	= idtypelist::alloc ();
    IDType		*	p;

    document::update_links (0, 1, "", updated);

    for (p = idtypelist::first (updated); p; p = idtypelist::next (updated))
    {
        wlog ("", "# %d\t'%s'\n", idtype::id (p), idtype::stringid (p));
    }

    return 0;
}

v3.3 R2489, 06.06.2011

priint:comet InDesign® Plug-Ins

static int document::export_styles(
  ItemRef docRef = 0,
  char* destPathAndBaseName = 0,
  int fileFlag = 1)

XML-Export of document styles and colors.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef 0 Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
destPathAndBaseName String or char* "" Path and base name for export files. Styles export will be written to destPathAndBaseName_Styles.xml and colors to destPathAndBaseName_Graphic.xml

"" : Path and base name of docRef (must not be new and unsaved in this case!)
fileFlag int 1 Remove existing export files?

0 : No
1 : Yes

v3.3 R2580, 1. Aug. 2011

priint:comet InDesign® Plug-Ins

static int document::get_styles(
  ItemRef docRef,
  char* styleClass,
  StringList resultList)

Collect all style names of a document. The names of all available styles of one class will be including their folder path inserted into a list. The path separator is ':'.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
styleClass char* oder String - Which style names should be collected?

"parastyles" : Paragraph styles
"charstyles" : Character styles
"objstyles" : Object styles
"tablestyles" : Table styles
"cellstyles" : Cell styles
resultList StringList - Result list

Please note
  1. The list must be allocated with stringlist::alloc before using it!
  2. The list is emptied before execution.

Write all available paragraph styles of the current document into the log file. 

int main ()
{
    StringList	li 	= stringlist::alloc ();
    char	*	str;

    document::get_styles (0, "parastyles", li);

    for (str = stringlist::first (li); str; str = stringlist::next (li))
    {
        wlog ("", "--%s--\n", str);
    }

    stringlist::release (li);
    return 0;
}

v4.1 R24333, 6. Dez 2018

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CDocument.getStyleNames

static int document::import_styles(
  ItemRef docRef,
  char* whatStyles,
  char* sourceDocument,
  int clashResolution = 0)

Import styles from another document.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
whatStyles char* oder String - Types of formats to import. The following (case insensitive) styles types are supported:

"paraStyles" : Paragraph styles
"charStyles" : Character styles
"textStyles" : Paragraph and character styles
"tableStyles" : Table styles
"cellStyles" : Cell styles
"tableAndCellstyles" : Table and cell styles
"tocStyles" : Table of content styles
"strokeStyles" : Stroke styles (Not supported by comet_pdf.)
"objectStyles"</i> : Object styles

"all" : All styles
sourceDocument char* oder String - Complete path of the document from which the styles are to be imported.
clashResolution int 0 Strategy for resolving conflicts with name matches

0 : Does not import styles whose names clash with existing items
br/> 1 : Overwrite existing styles whose names clash with imported items
br/> 2 : Renames imported styles whose names clash with existing items to preserve existing items

Note for comet_pdf : If only cell styles are imported missing paragraph styles used in cell styles are also imported. But existing paragraph styles are not overwritten in this csse. If i.e. the cell style Z is imported with the paragraph style A, then A is imported if there is not yet a paragraph style A. If A already exists, the paragraph style A is left unchanged.

The same applies analogously when importing table styles for the used cell styles and their paragraph styles. 

result = document::import_styles (0, "tableAndCellStyles", "$DESKTOP/naiv.indd", 0);

v4.1.6 R25778, 11. Sep. 2019
comet_pdf support since v4.1.8, R27723

priint:comet InDesign® Plug-Ins, comet_pdf

static int document::show_folio(ItemRef docRef = 0)

Open the Folio preview of a given document. Supported since InDesign® CS 5.5.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef 0 Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)

v3.3 R2670, 14. Okt. 2011 and InDesign® CS5.5

priint:comet InDesign® Plug-Ins

static int document::get_notes_printable(ItemRef docRef = 0)

document::notes::get_printable

static int document::set_notes_printable(ItemRef docRef = 0, int newState = 0)

document::notes::set_printable

static int document::get_masterpages(
  ItemRef docRef,
  IDTypeList resultList,
  int unusedOnly = 0,
  int sortedByBasedOn = 1)

Get information about the parent pages/spreads of a given document.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
resultList IDTypeList - Allocated list for results. The list entries containing the following values

idtype::stringid () : Name of parent spread
idtype::id () : UID
idtype::id2 () : Number of parent pages in spread
idtype::id3 () : UID of ancestor
unusedOnly int 0 since V4.1.6 R25778 Get only the unused parent pages of the document
sortedByBasedOn int 1 ab V4.1.6 R25778 Sort order in result list:

1 : The result list is sorted such that parents with other parents applied to them are later in the list than the parents they derive from.

0 : Same sequence order like in panel Pages. 
int main ()
{
    IDTypeList		masters	= idtypelist::alloc ();
    IDType			master;

    document::get_masterpages (0, masters);
    for (master = idtypelist::first (masters); master; master = idtypelist::next (masters))
    {
        wlog ("", "%s	[UID %d, %d page(s), Ancestor %d]\n", 
         	idtype::stringid (master),
         	idtype::id (master),
         	idtype::id2 (master),
         	idtype::id3 (master));
    }

    return 0;
}

v3.3 R3091, 20.07.2012
Parameter unusedOnly since v4.1.6 R25778, 16. Sep 2019
Parameter sortedByBasedOn since v4.1.6 R25778, 16. Sep 2019

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CDocument.getMasterPageInfo

static int document::import_masterpage(
  ItemRef docRef,
  char* orgPath,
  char* master_name,
  int overrideExisting = 0,
  int openAsCopy = 0)

Import/update parent spread(s) of a document from another document. All ancestors of the parent spread are automatically imported/updated too.

If the source document is not already opened, the document is opened in the background and closed at the next idle time. Do NOT change this document in this case!

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
orgPath String or char* - complete path to the source document
master_name String or char* - complete parent spread name (C-Parent)

All ancestors of this parent are imported/updated too.
overrideExisting int 0 Update existing parent spreads?

0 : no
1 : yes. All overrides of the updated parent spreads will be removed automatically in this case.
openAsCopy int 0 Open mode of file

0 : Open normally. If the file is already open, this document will be used.

1 : Open as copy. Unsaved changes in another document window of the same source file are ignored. 
int main ()
{
    int			res;

    res = document::import_masterpage (
     	0, 
     	"$DESKTOP/myParents.indd",
     	"C-Parent",
     	1);

    wlog ("", "import_masterpage result %d\n", res);
    return 0;
}

v3.3 R3091, 20.07.2012

priint:comet InDesign® Plug-Ins

Parameter openAsCopy since v4.1 R24334, 17. Dec 2018
import_masterpages

static int document::import_masterpages(
  ItemRef docRef,
  char* sourceDocument,
  int clashResolution = 0)

Import all parent pages from another document. Deleted parent page frames that have been overwritten in the target (see frame::is_overriden_masteritem) are retained during import.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
sourceDocument char* oder String - Complete path of the document from which the parent spreads are to be imported.
clashResolution int 1 Strategy for resolving conflicts with name matches

1 : Overwrite existing parents whose names clash with imported items
br/> 2 : Renames imported parents whose names clash with existing items to preserve existing items 
int main ()
{
    int res = document::import_masterpages (0, "$DESKTOP/m_src.indd", 1);

    wlog ("", "Import masterpages result : %d", res);
    return 0;
}

v4.1.6 R25778, 16. Sep. 2019

priint:comet InDesign® Plug-Ins, comet_pdf

import_masterpage

static int document::remove_masterpage(ItemRef docRef, char* master_name)

Remove a parent spread from a given document.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
master_name String or char* - Complete parent spread name (C-Parent) 
int main ()
{
    int			res;

    res = document::import_masterpage (
     	0, 
     	"$DESKTOP/myMasters.indd",
     	"C-Parent",
     	1);

    wlog ("", "import_masterpage result %d\n", res);
    return 0;
}

v4.1.6 R25788, 16. Sep 2019

priint:comet InDesign® Plug-Ins

import_masterpages

static int document::move_masterpage(
  ItemRef docRef,
  char* master_name,
  char* before)

Move a parent page entry in the list of parent pages on the panel Pages.

The call has no influence on the appearance of the document. It only changes the order of the parent pages in the panel Pages

For some reason that we cannot understand, the instruction cannot be undone.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
master_name String or char* - complete parent spread name (C-Parent)
before String oder char* - Before which parent the entry spread should be moved?

"" or non-existing parent page : Move to the end

v4.1.6 R25788, 16. Sep 2019

priint:comet InDesign® Plug-Ins

static int document::dump_uidtranstable(ItemRef docRef = 0)

Internal use only.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)

v3.3 R3500, 07.03.2012

priint:comet InDesign® Plug-Ins, comet_pdf

static int document::cometgroup_recreated(
  ItemRef docRef,
  int oldGroupID,
  int newGroupID)

Reset a Comet group ID. After replacing products (Comet groups) you may wish to have the same Comet group ID for the new Comet group. To solve this problem, keep the current ID in a variable, replace the Comet group and reset the new Comet group ID by the old one.

Use existing Comet group IDs only! Wrong numbers may cause serious errors!

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
oldGroupID int - Comet group ID before replacing
newGroupID int - Group ID after replacing
#include "internal/types.h"

Collect all Comet group of a document and replace some of them by prepared snippets. To run the script, please create a new action first with the implementation given in the next example and replace MY_COMPARE_SCRIPT by the ID of this new action. 

#include "internal/types.h"

int get_snippet (IDType id)
{
    if (idtype::id (id) == 0) return 0;
    if (strcmp (idtype::stringid (id), "109007") == 0)	return 617;
    if (strcmp (idtype::stringid (id), "109507") == 0)	return 621;
    if (strcmp (idtype::stringid (id), "107507") == 0)	return 623;

    return 0;
}

IDType get_id (ItemRef fr, IDType id)
{
    int			i;
    char		base [255];
    char		slot [255];

    idtype::set_id (id, 0);
    if (!frame::get_cometgroup (fr)) return id;

    for (i = 0; i < 2; i++)
    {
        if (i == 0)	strcpy (base, "BuiltBy");
        else		strcpy (base, "");
        idtype::set_id (id, placeholder::get_value (fr, sprintf (slot, "%d%s", base, "ID")));
        idtype::set_id2 (id, placeholder::get_value (fr, sprintf (slot, "%s%s", base, "ID2")));
        idtype::set_id3 (id, placeholder::get_value (fr, sprintf (slot, "%s%s", base, "ID3")));
        idtype::set_stringid (id, placeholder::sget_value (fr, sprintf (slot, "%s%s", base, "StringID")));

        if (idtype::id (id)) break;
    }

    return id;
}

int replace (ItemList oldFrames)
{
    ItemList		newFrames	= 0;
    ItemRef			fr			= item::alloc ();
    IDType			id			= idtype::alloc ();
    int				snippet;
    float			l, t, r, b;
    int				pg, gid, new_gid;
    char			lay	[512];

    while (1)
    {
        // Sanity check
        itemlist::get (oldFrames, fr, 0);
        if (!frame::is_valid (fr)) break;

        // Do we have to replace this Comet group?
        snippet = get_snippet (get_id (fr, id));
        if (!snippet) break;

        // Get old states
        pg	= page::get (fr);
        gid	= frame::get_cometgroup (fr);
        frame::get_layer (fr, lay);
        itemlist::bbox (oldFrames, &l, &t, &r, &b);

        wlog ("", "'%s' replace by snippet %d\n", idtype::stringid (id), snippet);

        // Remove old, create new
        itemlist::remove_items (oldFrames);
        newFrames = document::place_items (0, 0, 0, snippet, l, t, pg, lay);

        // Reset comet group id
        itemlist::get (newFrames, fr, 0);
        new_gid = frame::get_cometgroup (fr);
        document::cometgroup_recreated (0, gid, new_gid);

        break;		// ready
    }

    item::release (fr);
    idtype::release (id);
    itemlist::release (newFrames);

    return 0;
}

int main ()
{
    ItemListList		lli;
    ItemList			li;
    ItemList			docFrames	= itemlist::allframes ();

    if (gRun > 1)	return 0;

    lli = itemlist::logical_groups (docFrames, kSearchDocument, "", 1, "script", MY_COMPARE_SCRIPT);

    for (li = itemlistlist::first (lli); li; li =  itemlistlist::next (lli))
    {
        replace (li);
    }

    itemlist::release (docFrames);
    itemlistlist::release (lli);

    return 0;
}

Function for the above example. 

int main ()
{
    int		group1	= frame::get_cometgroup (gMasterFrame);
    int		group2	= frame::get_cometgroup (gCheckFrame);

    if (!gCheckFrame)
    {
        if (!group1)	return 0;
        return 0;
    }

    return (group1 != group2);
}

v3.3 R3500, 07.03.2012

priint:comet InDesign® Plug-Ins

static int document::get_pageref(
  ItemRef outRef,
  ItemRef docRef,
  int pg)

Get the UID of a page.

Name Type Default Description
Return int   0 or ErrorCode
outRef ItemRef - Allocated variable of type ItemRef for the resulting page ref
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
pg int - 1-based index of interested page 
int main ()
{
    int			pg            = page::get (gFrame);
    int     	indexInSpread;
    int			spread        = page::get_spread (0, pg, &indexInSpread);
    ItemRef		pageRef       = item::alloc ();
    ItemRef		spreadRef     = item::alloc ();

    document::get_pageref (pageRef, 0, pg);
    document::get_spreadref (spreadRef, 0, spread);

    wlog ("", "Spread %d (%d), Seite %d (%d), %d. page in Spread\n",
     		spread, item::getint (spreadRef),
      		pg, item::getint (pageRef), indexInSpread);

    return 0;
}

v3.3 R3500, 08.03.2012

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CPage.getUID

static int document::get_spreadref(
  ItemRef outRef,
  ItemRef docRef,
  int spreadIndex)

Get the UID of a spread given by its index. To get the spread index of a page, use page::get_spread.

Name Type Default Description
Return int   0 or ErrorCode
outRef ItemRef - Allocated variable of type ItemRef for the resulting page ref
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
pg int - 0-based spread index of interest. To get the spread index of a page, use page::get_spread. 
int main ()
{
    int			pg            = page::get (gFrame);
    int			indexInSpread;
    int			spread        = page::get_spread (0, pg, &indexInSpread);
    ItemRef		pageRef       = item::alloc ();
    ItemRef		spreadRef     = item::alloc ();

    document::get_pageref (pageRef, 0, pg);
    document::get_spreadref (spreadRef, 0, spread);

    wlog ("", "Spread %d (%d), Seite %d (%d), %d. page in Spread\n",
     		spread, item::getint (spreadRef),
     		pg, item::getint (pageRef), indexInSpread);

    return 0;
}

v3.3 R3500, 08.03.2012

priint:comet InDesign® Plug-Ins, comet_pdf

page::get_spread

static int document::has_overset(
  ItemRef docRef,
  ItemList frames = 0,
  ItemList tables = 0,
  IDTypeList cells = 0)

Is there at least one text or table cell with overset text in the document?

Name Type Default Description
Return int   0 : No overset text or error
1 : At least one text frame or one table cell has overset text
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
frames ItemList 0 (out parameter) Frames with text overset
tables ItemList 0 (out parameter) Tables with cells with text overset. The list has the same length as cells and the i-th entry in the list is the table reference of the i-th entry in cells.
cells IDTypeList 0 (out parameter) The list contains an entry of type IDType for every overseted cell with the following data:

idtype::id : 0-based column
idtype::id2 : 0-based row
idtype::id3 : UID of table. See item::define for more information about how to use UIDs. Alternatively, the corresponding table reference can also be determined from the list tables using the same list index.
#include "internal/types.h"
#include "internal/table.h"
#include "internal/text.h"
#include "internal/products.h" 
int main ()
{
    ItemList		frames	= itemlist::alloc ();
    ItemList		tables	= itemlist::alloc ();
    IDTypeList		cells	= idtypelist::alloc ();
    int				ov;

    ov = document::has_overset (0, frames, tables, cells);
    if (ov)
    {
        wlog ("", "# Oversets : %d frame(s), %d table(s), %d cells(s)\n",
         		itemlist::length (frames),
         		itemlist::length (tables),
         		idtypelist::length (cells));
    }

    return 0;
}

Create red frames over all table cells with overset. The red frames should be created on the layer 'Overset. 

#include "internal/types.h"
#include "internal/table.h"
#include "internal/text.h"
#include "internal/products.h"

int main()
{
    checkAndMarkOversets();
    return 0;
}

int checkAndMarkOversets()
{
    ItemList 	frames 		= itemlist::alloc();
    ItemList 	tables 		= itemlist::alloc();
    IDTypeList 	cells 		= idtypelist::alloc();
    int 		ov;
    char	* 	layerName 	= "Overset";

    layer::remove(layerName);
    layer::add(layerName, "");
    ov = document::has_overset(0, frames, tables, cells);
    if (ov) 	handleOversetTable(tables, cells);

    itemlist::release(frames);
    itemlist::release(tables);
    idtypelist::release(cells);

    return 0;
}

int handleOversetTable(ItemList tableList, IDTypeList cellList)
{
    ItemRef 	fr 		= item::alloc();
    ItemRef 	nFrame 	= item::alloc();
    IDType 		idType;
    char 	*	layerName = "Overset";
    char 	*	colorName = "Overset";
    int 		c, r;
    Table 		t = table::alloc();
    float 		x, y, x2, y2;
    float 		fx, fy, fx2, fy2;
    int 		i, j;

    color::define_cmyk(colorName, 0.0, 1.0, 1.0, 0.0);
    for (i = 0; i < itemlist::length(tableList); i++)
    {
        itemlist::get(tableList, t, i);  Tabelle aus der Liste abfragen
        idType = idtypelist::get(cellList, i);
        if (table::is_valid(t))
        {
            c = idtype::id(idType);
            r = idtype::id2(idType);
            if (c < table::columns(t) && r < table::rows(t))
            {
                table::get_cellbox(t, c, r, kFrameRelative, &x, &y, &x2, &y2, fr);
                frame::bbox(fr, &fx, &fy, &fx2, &fy2);
                frame::create2(nFrame, kRectangle, fx + x, fy + y, fx + x2, fy + y2, page::get(fr), layerName);
                frame::color(nFrame, colorName);
                frame::set_blending(nFrame, kBlendingBasic, 20.0);
            }
        }
    }

    table::release(t);
    item::release(fr);
    item::release(nFrame);

    return 0;
}

v4.0.4 R7740, 01 Apr 2015

priint:comet InDesign® Plug-Ins

static int document::write_frame_info(
  ItemRef document,
  int frameSearchFlags,
  int documentType,
  int conflictBehavior,
  int frameType = 0,
  int page = -2,
  LinkList placeholders = 0)

Store all information about frames in the document to the data sources. More information at Frame infos

Name Type Default Description
Return int   0 or ErrorCode
document ItemRef - Document
frameSearchFlags int kUseDefault How should frame infos to overwrite be identified?
See frame::write_frame_info
documentType int kLocalDoc In which document scope should we search for existing frame infos?
See frame::write_frame_info
conflictBehavior int kThrowError Behavior when multiple search results are found per frame
See frame::write_frame_info
frameType int - Frame type to write
0: All
1: Text frame
2: Graphic frame
page int -2 From which page should the frames be written?
-2: All pages
placeholders LinkList 0 Only respect placeholders in this list
#include "internal/frameinfos.h"

Write all frames of the document 

int main ()
{
    return document::write_frame_info(gDocument);
}

Only write graphic frames from page 4 

int main ()
{
    document::write_frame_info(gDocument, 2, 4);
    return 0;
}

v4.0.5 R8423

priint:comet InDesign® Plug-Ins, comet_pdf

frame::write_frame_info
itemlist::write_frame_info
document::apply_frame_info

static int document::apply_frame_info(
  ItemRef document,
  int propertyFlags,
  int searchType,
  int documentType,
  int page = -2,
  int frameType = 0,
  LinkList placeholders = 0)

Restore saved information about a frame from the data sources and set it back to the frames. More information at Frame infos

Name Type Default Description
Return int   0 or ErrorCode
document ItemRef - Document
propertyFlags int - Which information should be restored?
See frame::apply_frame_info
frameSearchFlags int kUseDefault How should the document source be identified?
See frame::apply_frame_info
documentType int kLocalDoc How should the stored frame be identified?
See frame::apply_frame_info
conflictBehavior int kThrowError Behavior when multiple search results are found per frame
See frame::apply_frame_info
page int -2 Restore frame information on which page?
-2: All pages
frameType int 0 Only respect frames of type
0: All
1: Text frame
2: Graphic frame
placeholders LinkList 0 Only respect placeholders in this list
#include "internal/frameinfos.h"

Restore all properties of all frames in the current document 

#include "internal/frameinfos.h"

int main ()
{
    int propertyFlags =
     			kApplyScriptTags
     			+ kApplyXPosAbs
     			+ kApplyYPosAbs
     			+ kApplyWidth
     			+ kApplyHeight
     			+ kApplyFrameRotate
     			+ kApplyFrameSkew
     			+ kApplyImageXOffset
     			+ kApplyImageYOffset
     			+ kApplyImageXScale
     			+ kApplyImageYScale
     			+ kApplyImageRotate
     			+ kApplyImageSkew;

    document::apply_frame_info(gDocument, propertyFlags, kUseDefault, kLocalDoc, kThrowError);
    return 0;
}

v4.0.5 R8423

priint:comet InDesign® Plug-Ins, comet_pdf

frame::apply_frame_info
itemlist::apply_frame_info
document::write_frame_info

static int document::delete_frame_info(
  ItemRef docRef,
  int frameSearchFlags = kUseDefault,
  int documentType = kLocalDoc,
  int conflictBehavior = kThrowError,
  int page = -2,
  int frameType = 0,
  LinkList placeholders = 0)

Delete saved information about the document's frames from the data sources.

Important: This function only deletes frame infos for the current frames of the document. This is a convenience function for easily gathering the document's frames. More information at Frame infos

Name Type Default Description
Return int   0 or ErrorCode
document ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
frameSearchFlags int kUseDefault How should the document source be identified?
See frame::apply_frame_info
documentType int kLocalDoc How should the stored frame be identified?
See frame::apply_frame_info
conflictBehavior int kThrowError Behavior when multiple search results are found per frame
See frame::apply_frame_info
page int -2 Restore frame information on which page?
-2: All pages
frameType int 0 Only respect frames of type
0: All
1: Text frame
2: Graphic frame
placeholders LinkList 0 Only respect placeholders in this list
#include "internal/frameinfos.h"

Delete all properties of all frames in the current document 

#include "internal/frameinfos.h"
int main ()
{
    document::delete_frame_info(gDocument);
    return 0;
}

v4.0.5 R8423

priint:comet InDesign® Plug-Ins, comet_pdf

frame::apply_frame_info
itemlist::apply_frame_info
document::write_frame_info

static int document::delete_frame_info2(ItemRef docRef)

Delete saved frame infos for this document data sources.

Important: This function deletes all frame infos ever stored for the current document. More information at Frame infos

Name Type Default Description
Return int   0 or ErrorCode
document ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)

Delete all stored frame infos of the current document 

int main ()
{
    document::delete_frame_info2(gDocument);
    return 0;
}

v4.0.5 R9930

priint:comet InDesign® Plug-Ins, comet_pdf

document::delete_frame_info

static int document::create_mission_ui(ItemRef docRef, ItemList frames = 0)

Opens the dialog for creating missions.

A frame list can be provided as a parameter to create missions for these frames. More information at Missions

Name Type Default Description
Return int   0 or ErrorCode
document ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
duplicateBehavior int 0 What should happen if the mission already exists?
0 - Don't create
1 - Move the first existing mission to bottom of list and delete the rest
2 - Create new mission as duplicate
frames ItemList 0 Frames for which missions should be created.

Shows the input dialog with different behavior for duplicates depending on keys pressed. Can create missions for the selected frames. 

int main()
{
    ItemList 	selected;

    selected = itemlist::selected();

    if (gRun == 1)
    {
        if (system::shiftkey())
        {
            document::create_mission_ui(gDocument, 1, selected); // Move
        }
        else if (system::cmdkey())
        {
            document::create_mission_ui(gDocument, 2, selected); // Duplicate
        }
        else
        {
            document::create_mission_ui(gDocument, 0, selected); // Skip
        }
    }

    itemlist::release(selected);

    return 0;
}

v4.0.5 R10150

priint:comet InDesign® Plug-Ins

document::execute_missions
document::delete_missions
document::count_missions
document::remove_duplicate_missions

static int document::execute_missions(
  ItemRef docRef,
  int deleteAfterDone = 1,
  int alsoDeleteFailed = 0)

Executes all Missions of the document. A frame list can be provided as a parameter to create missions for these frames. More information at Missions

Name Type Default Description
Return int   0 or ErrorCode
document ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
deleteAfterDone int 1 Delete missions after execution?
0 - No
1 - Yes
alsoDeleteFailed int 0 Also delete missions which failed to execute? Has no effect when deleteAfterDone is 0.
0 - No
1 - Yes

Executes all missions of the document. Successful ones are deleted, failed ones not. 

int main ()
{
    document::execute_missions(gDocument, 1, 0);

    return 0;
}

v4.0.5 R10150

priint:comet InDesign® Plug-Ins

document::create_mission_ui
document::delete_missions
document::count_missions
document::remove_duplicate_missions

static int document::count_missions(ItemRef docRef, int* count)

Counts the number of missions in the document. More information at Missions

Name Type Default Description
Return int   0 or ErrorCode
document ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
count int* - Result mission count

Shows a message containing the number of missions in the document. 

int main ()
{
    int 	count = 0;

    document::count_missions(gDocument, &count);
    showmessage("%d", count);

    return 0;
}

v4.0.5 R10150

priint:comet InDesign® Plug-Ins

document::create_mission_ui
document::execute_missions
document::delete_missions
document::remove_duplicate_missions

static int document::delete_missions(ItemRef docRef)

Deletes all missions from the document. More information at Missions

Name Type Default Description
Return int   0 or ErrorCode
document ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)

Delete all missions of the document. 

int main ()
{
    document::delete_missions(gDocument);

    return 0;
}

v4.0.5 R10102

priint:comet InDesign® Plug-Ins

document::create_mission_ui
document::execute_missions
document::count_missions
document::remove_duplicate_missions

static int document::remove_duplicate_missions(ItemRef docRef)

Removes all duplicates of all missions in the document, leaving only one instance of each mission.

More information at Missions

Name Type Default Description
Return int   0 or ErrorCode
document ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)

Delete all missio duplicates s of the document. 

int main ()
{
    document::remove_duplicate_missions(gDocument);

    return 0;
}

v4.0.5 R10102

priint:comet InDesign® Plug-Ins

document::create_mission_ui
document::execute_missions
document::count_missions
document::delete_missions

static int document::prepare_translations(
  ItemRef docRef,
  int placeholderID,
  int autoStore,
  int get_record_id_func,
  IDType recordID,
  int behavior = 0)

Prepare a document for automatic translations. All existings text placeholders are removed first. Then, every piece of text is linked against a new placeholder. This pieces are delimited by (of course) the text begin and end and by tables, inlines and table cells. To calculate new record IDs, the function get_record_id_func is called for every new placeholder.

The given placeholder placeholderID must by defined and of type text!

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
placeholderID int - ID of a defined text placeholder in the data pool
autoStore int - Automatically store the new placeholders.?

0 : no
1 : yes, the store script is called for every new placeholder
get_record_id_func func_ptr - Name of function to calculate the new record IDs. You simply give it the name of an existing function of type

int my_function (IDType myRecordID, int placeholderID)

The IDType myRecordID must be declared and allocated outside this function. See example to learn more.

Return value of get_record_id_func

1 : Create and link the placeholder
0 : Do not create placeholder
recordID IDType - Allocated IDType for calculations in calls to get_record_id_func
behavior int 0 How to deal with existing placeholders of the text?

0 : Replace all placeholders
1 : Retain placeholders with ID placeholderID, replace all others
2 : Retain all placeholders

Indeed, its easy! In the example the function get_record_id is implemented with the approriate type. Before using it, we have to allocate an IDType. Thats all, you now can call prepare_translations. Its creating the placeholders as described above and will call get_record_id everytime a new placeholder is needed. 

int main ()
{	
    IDType		recordID	= idtype::alloc ();

    idtype::set_id (recordID, 100);
    document::prepare_translations (0, 360, 1, get_record_id, recordID);

    return 0;
}

int get_record_id (IDType rid, int placeholderID)
{
    idtype::set_id (rid, idtype::id (rid)+1);
    idtype::set_id2 (rid, 0);
    idtype::set_id3 (rid, 0);
    idtype::set_stringid (rid, "");

    return 1;
}

Parameter behavior seit R20457, 13. Okt 2017 v4.0.4 R7740, 01 Apr 2015

priint:comet InDesign® Plug-Ins

static int document::link_with_unique_placeholder(
  ItemRef docRef,
  int placeholderID,
  int autoStore,
  int get_record_id_func,
  IDType recordID)

Synonym for prepare_translations.

document::prepare_translations

static int document::schwarzfilmtausch(ItemRef docRef)

Prepare document for the so called 'Schwarzfilmtausch'. To avoid moving around colored parts of the document we lock all frames and all table row heights of the document. In addition, all layout rules and all nails and magnets are removed from the document.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)

v4.0.5 R9660, 19 Nov 2015

priint:comet InDesign® Plug-Ins, comet_pdf

static int document::get_blendingspace(ItemRef docRef)

Get the transparency blending space of a document.

Name Type Default Description
Return int   -1 : Error
1 : RGB
2 : CMYK
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)

v4.0.5 R9813, 8 Jan 2016

priint:comet InDesign® Plug-Ins, comet_pdf

static int document::set_blendingspace(ItemRef docRef, int blendSpace)

Set the transparency blending space of a document.

If the document is printed later, take care on the appropriate setting here! Wrong settings may lead to wrong print results!

Here you can see the same frames at first in a RGB transparency blending space and then in CMYK:

        

    

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
blendSpace int - new transparency blending space

0 : Default
1 : RGB
2 : CMYK

Toggle transparency blending space. 

int main ()
{
    int		blendingspace	= document::get_blendingspace (0);

    if (blendingspace == 1)			document::set_blendingspace (0, 2);
    else if (blendingspace == 2)	document::set_blendingspace (0, 1);

    return 0;
}

v4.0.5 R9813, 8 Jan 2016

priint:comet InDesign® Plug-Ins, comet_pdf

static int document::preflight(
  ItemRef docRef,
  char* profile,
  char* output,
  int maxlen = 0)

Preflight a document to check for errors. The preflight profile has to be defined by its name or by a complete path to an idpp file. To define preflight profiles in InDesign® (Desktop) you may use the Preflights panel. Under InDesign® Server you can install new preflight profiles by calling this line of JavaScript:

app.loadPreflightProfile(File(profilepath));

Under comet_pdf the commend is NOP.

Name Type Default Description
Return int   Fehlercode or 0

1289 (preflightNotEmptyErr) : Preflight successfully done and found some errors.
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
profile String or char* - Name or path of preflight profile. If you use a path (extension idpp) please take care about its name: File name and profile name must be equal. Otherwise every call of the function will create a new numbered) version of the profile.
output String or char* - Allocated result string

"" : Results will be written into this string. Take care to allocate this string big enough when using char*!

Complete path with extension 'pdf' or 'txt' : Write results to the given file. If a file already exists, it will be overridden. InDesign® Server does NOT support PDF export here!
maxlen int 0 Size of output in bytes incl. the closing 0. The parameter is used only if output is empty ("") and of type char*. Results longer than maxlen are cut off at maxlen-1 bytes. 
int main ()
{
    char		txt [100000];
    int			result;

    if (system::shiftkey ()) strcpy (txt, "$DESKTOP/aaa.pdf");
    result = document::preflight (0, "$DESKTOP/aaa.idpp", txt);
    wlog ("", "%d\n-------------------\n%s\n", result, txt);

    return 0;
}

This is somewhat more difficult with Javascript. We are only showing it here for the sake of completeness. Attention: In this example, the preflight profile used (here profile_comet) must be embedded in the document! 

var myPath 		= "/Users/paul/Desktop/preflight.indd"
var preflightName	= "profile_comet";
var reportPath	= "/Users/paul/Desktop/report.pdf";
var reportPathTxt	= "/Users/paul/Desktop/report.txt";
var gOptions    	= app.comet.ping () + ";-1;";

function checkPreflight()
{
    var myDoc 		= app.documents[0];
    var turnOff		= false;

    if (myDoc.preflightOptions.preflightOff)
    {
        myDoc.preflightOptions.preflightOff = false;
        turnOff		= true;
    }

    var myProfile 	= undefined;
    for (var tk = 0;tk < myDoc.preflightProfiles.length; tk++)
    {
        var prefLightname	= myDoc.preflightProfiles[tk].name;
        if( prefLightname == preflightName)
        {
            myProfile	= myDoc.preflightProfiles[tk];
            break;
        }
    }

    if (myProfile == undefined)
    {
        alert ("Preflight profile " + preflightName + " not found!");
        if (turnOff) myDoc.preflightOptions.preflightOff = true;
        return;
    }

    var allProcess	= app.preflightProcesses;
    var myPreflight = app.preflightProcesses.add(myDoc, myProfile); 	// Set the preflight var

    myPreflight.waitForProcess(); 									// Don't process the results until it has finished running

    if (app.name.indexOf ('Server') > 0)
    {
        var results 	= myPreflight.aggregatedResults[2]; 			// Store the results in a variable
        var errorLog 	= File(reportPathTxt);
        errorLog.open("w");
        for (var x = 0; x < results.length; x++)
        {
            errorLog.write(results[x]);
            errorLog.write("\n");
        }
        errorLog.close();
    }
    else
    {
        myPreflight.saveReport (File (reportPath));
    }

    if (turnOff) myDoc.preflightOptions.preflightOff = true;
}

app.comet.use ("##type:xmlfolder;folder:$DESKTOP/fifo/priint 5.5/xmldata", "", "", false, "");
app.comet.documentOpen (myPath, true, gOptions);
checkPreflight();
app.comet.documentClose (myPath, gOptions);

Parameter maxlen sinc e v4.0.5 R14201, 13. Dez 2016
v4.0.5 R10224, 1. March 2016

priint:comet InDesign® Plug-Ins, comet_pdf

static int document::export_color_profiles(
  ItemRef docRef,
  char* destfolder,
  char* destXML = 0)

Export color profiles of a given document. The function exports the RGB and CMYK color profiles used in a given document. If the document uses a global color space, the profile of the workspace space is exported.

Name Type Default Description
Return int   Fehlercode or 0
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
destfolder String or char* - Export destination for the icc file. The export copies the profile file into the subfolder rgb or cmyk of the given folder. Missing folders are created automatically Existing target files are overwritten.
destXML String or char* 0 Full path of a colorprofiles.xml. The profile data of the exported color profiles are inserted into/updated in the specified XML. If the XML does not exist, it is created.

0: Ignore 
int main ()
{
    document::export_color_profiles (0, "$DESKTOP/aaabbb", "$DESKTOP/aaabbb.xml");

    return 0;
}

v4.0.5 R13799, 6. Oct 2016

priint:comet InDesign® Plug-Ins, comet_pdf

static int document::get_color_profiles(
  ItemRef docRef,
  char* rgbProfile = 0,
  char* cmykProfile = 0,
  char* priority = 0)

Determine the names of the color profiles set in the document.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
rgbProfile String or char* 0 Name of the RGB profile

0 : Ignore return value
cmykProfile String or char* 0 Name of the CMYK profile

0 : Ignore return value
priority String or char* 0 Rendering Intention. One of the following values is returned:

perceptual
saturation
relative
absolute
unknown

0 : Ignore return value

v4.1.8 R30410, 18. Mar 2022

priint:comet InDesign® Plug-Ins, comet_pdf

static int document::clean_storyscrap(ItemRef docRef = 0)

Remove unused text stories of a document. All documents, containing text imported by priint:priint:comet InDesign® Plug-Ins prior v4.0.5 R16180 are containing unused objects which may lead to some problems while using the documents under some rare circumstances. Using document::clean_storyscrap you can clean up these documents.

Remarks:

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)

v4.0.5 R16180, 19. Mar 2017

priint:comet InDesign® Plug-Ins, comet_pdf

static int document::show_invisibles(ItemRef docRef = 0, int state = -2)

Show/Hide invisible characters of texts of the document.

Name Type Default Description
Return int   Old state

-1 : Error
0 : Invisibles hidden
1 : Invisibles shown
docRef ItemRef 0 Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
int state -2 New state

-2 : Query state only
-1 : Toggle
0 : Hide invisibled
1 : Show invisibled

v4.1 R21000, 16. Nov 2017

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static int document::individualization(ItemRef docRef, char* dataFilePath)

Serialize a document, see here for more information about serializations.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document to serialize, see hier

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front) 0 : current front document
dataFilePath char* oder String - Complete path to serialization data file see here

The data type String si supported since v4.1 R23901!

Version v4.1, 1. Oct 2018

priint:comet InDesign® Plug-Ins, comet_pdf

static ItemList document::linked_urls(ItemRef docRef = 0)

Get all frames of a document which have a Web Image. General information about Web Images can be found here.

Name Type Default Description
Return ItemList   New ItemList containing only frames from the document with Web Images. Must be deleted using itemlist::release!
docRef ItemRef 0 Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)

Get the linked and embedded frames of a document 

int main()
{
    ItemList 	linked 			= document::linked_urls();
    ItemList 	embedded 		= document::embedded_urls();
    int 		linkedCount 	= 0;
    int 		embeddedCount 	= 0;

    if (linked)
    {
        linkedCount = itemlist::length(linked);
    }

    if (embedded)
    {
        embeddedCount = itemlist::length(embedded);
    }

    showmessage("%d frames are linked\n%d frames are embedded", framesCount, linkedCount, embeddedCount);

    itemlist::release(selected);
    if (linked)
    {
        itemlist::release(linked);
    }
    if (embedded)
    {
        itemlist::release(embedded);
    }

    return 0;
}

v4.0.5 R20002 (28. Jul 2017)

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

frame::has_linked_url
itemlist::linked_urls

static ItemList document::embedded_urls(ItemRef docRef = 0)

Get all frames of a document which have an embedded Web Image. General information about Web Images can be found here.

Name Type Default Description
Return ItemList   New ItemList containing only frames from the document with embedded Web Images. Must be deleted using itemlist::release!
docRef ItemRef 0 Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)

Get the linked and embedded frames of a document 

int main()
{
    ItemList 	linked 			= document::linked_urls();
    ItemList 	embedded 		= document::embedded_urls();
    int 		linkedCount 	= 0;
    int 		embeddedCount 	= 0;

    if (linked) {
        linkedCount = itemlist::length(linked);
    }

    if (embedded)
    {
        embeddedCount = itemlist::length(embedded);
    }

    showmessage("%d frames are linked\n%d frames are embedded", framesCount, linkedCount, embeddedCount);

    itemlist::release(selected);
    if (linked)
    {
        itemlist::release(linked);
    }
    if (embedded)
    {
        itemlist::release(embedded);
    }

    return 0;
}

v4.0.5 R20002 (28. Jul 2017)

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

frame::has_embedded_url
itemlist::embedded_urls

static ItemList document::check_url_links(
  ItemRef docRef = 0,
  ItemList outDated = 0,
  ItemList error = 0,
  int flags = 0)

Check all Web Images of the document. General information about Web Images can be found here.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef 0 Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
outdated ItemList 0 After execution, this list contains the frames with outdated images.
error ItemList 0 After execution, this list contains the frames for which the status check failed.
flags int 0 Flags

1 : Show progress

check all link states 

int main()
{
    ItemList 	outDatedFrames 		= itemlist::alloc();
    ItemList 	errorFrames 		= itemlist::alloc();
    int 		i 					= 0;
    int 		outDatedFramesCount = 0;
    int 		errorFramesCount 	= 0;

    document::check_url_links(gDocument, outDatedFrames, errorFrames, 1);
    errorFramesCount 	= itemlist::length(errorFrames);
    outDatedFramesCount	= itemlist::length(outDatedFrames);

    showmessage("%d frames are out of date.\nCould not get state for %d frames.", outDatedFramesCount, errorFramesCount);

    itemlist::release(errorFrames);
    itemlist::release(outDatedFrames);

    return 0;
}

v4.0.5 R19777 (24. Jul 2017)

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

frame::check_url_link
itemlist::check_url_links

static ItemList document::update_url_links(ItemRef docRef = 0, int flags = 0)

Update all Web Images of the document modified on server side. General information about Web Images can be found here. Please also note the rules for image placements of Web Images.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef 0 Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
flags int 0 Flags

1 : Show progress 
int main ()
{
    ItemList		missing 	= itemlist::alloc ();
    ItemList		outdated 	= itemlist::alloc ();
    int				result;

    if (!system::shiftkey ())
    {
        result = document::update_url_links (0, 1);
        if (result != 0)
        {
            showmessage ("Error %d while checking Web Images.", result);
        }
    }
    else
    {
        result = document::check_url_links (0, outdated, missing, 1);
        if (result == 0)
        {
            showmessage ("%d missing images, %d outdated images", 
             		itemlist::length (missing),
             		itemlist::length (outdated));
        }
        else
        {
            showmessage ("Error %d while checking Web Images.", result);
        }
    }

    return 0;
}

v4.0.5 R20002 (28. Jul 2017)

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

frame::update_url_link
itemlist::update_url_links

static ItemList document::remove_url_links(ItemRef docRef = 0)

Remove the Web Image links from all frames of the document. The images in the frames are untouched, only the links to the Web Images (th URLs) are removed. Generell information about Web Images you will find here.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef 0 Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front) 
int main ()
{
    document::remove_embedded_urls();
    return 0;
}

v4.0.5 R19777 (24. Jul 2017)

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

frame::remove_url_link
itemlist::remove_url_links

static char* document::get_image_url_folder(ItemRef docRef = 0)

Get the path for the downloads of Web Images of the document. Generell information about Web Images you will find here.

Name Type Default Description
Return char*   Path for Web Image downloads of the document. The document must not be new and UNSAVED.

The return value must not be changed and will be overwritten in subsequent calls of the function. See here to learn more about functions returning r/o char* values.

docRef ItemRef 0 Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)

v4.0.5 R20002 (28. Jul 2017)

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

document::update_url_links
document::check_url_links

static int document::set_pdf_accessibility_order(ItemRef docRef, int structOrder)

Specify which order should be used for the tags of Accessible PDFs, the 'normal' order resulting from the XY positions or the order configured in the Article panel? Manually the selection can be made using the menu Use for Tagging Order in Tagged PDFs of the Articles panel.

The setting is used only by the PDF export and only if 'Generell : Create Tagged PDF' (/GenerateStructure) is activated in the PDF Preset.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
structOrder int - Which order should be used?

1 : Article order
0 : InDesign default sorting

v5.0 R35050

priint:comet InDesign® Plug-Ins, comet_pdf

document::get_articles
get_pdf_accessibility_order

static int document::get_pdf_accessibility_order(ItemRef docRef)

Which order is used for the tags of accessible PDFs, the 'natural' order resulting from the XY positions of the frames or the order configured in the Articles panel? Manually the selection can be made using the menu Use for Tagging Order in Tagged PDFs of the Articles panel.

The setting is used only by the PDF export and only if 'Generell : Create Tagged PDF' (/GenerateStructure) is activated in the PDF Preset.

Name Type Default Description
Return int   0 : InDesign default sorting
1 : Article order
-1 : Error
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)

v5.0 R35050

priint:comet InDesign® Plug-Ins, comet_pdf

document::get_articles
set_pdf_accessibility_order

static int document::get_placeholder_visibility(ItemRef docRef = 0)

Get the visibility of document placeholders.

The function has no meaning using comet_pdf. Use option -ap here to show the placeholders in the resulting PDF, see here for more information.

Name Type Default Description
Return int   Current visibiltiy

0 : Hidden
1 : Visible
2 : Visible with state

-1 : Error
docRef ItemRef 0 Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)

v4.1 R23010, 9. May 2018

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

set_placeholder_visibility

static int document::set_placeholder_visibility(
  ItemRef docRef = 0,
  int newState = 0,
  int suppressUI = 0)

Set the visiblity of document placeholders.

The function has no meaning using comet_pdf. Use option -ap here to show the placeholders in the resulting PDF, see here for more information.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef 0 Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
newState int 0 New visiblity

0 : Hide
1 : Show
2 : Show with Status
suppresUI int 0 On large documents, a progress is shown automatically. Shall I suppress the progress bar?

0 : No, show progress bar if needed
1 : Yes, suppress progress bar zeigen
No effect in Illustrator

v4.1 R23010, 9. May 2018

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

get_placeholder_visibility

static int document::notes::export_(
  ItemRef docRef = 0,
  char* destPath = 0,
  String destString = 0,
  int flags = 4)

Export Comet notes of a document. Be careful with destString, its a String not a char*.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef 0 Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
destPath String or char* "" Destination path for the resulting xml file. If destString is defined and not 0, destPath is ignored.
destString String 0 Destination string for export, must be allocated using string::alloc. If the value is 0 destPath is used to export.
flags int kUseDocumentPath export flags

0 : no flags
kUseDocumentPath : Use document path and name with the extension xml as export file
kNoHiddenNotes : Suppress exporting hidden notes
#include "internal/types.h"

Export all Comet notes of the current document. The document must not be new (but can be modified). 

int main ()
{
    int 		result;

    result = document::export_notes ();
    wlog ("# Exporting all notes returned result code %d\n", result);

    return 0;
}

Export to a string. 

#include "internal/types.h"

int main ()
{
    int 			result;
    String			d		= string::alloc ();
    char		*	s;
    XMLTree			tree;
    char			title	[512];
    long			id;

    result = document::export_notes (0, "", d);
    if (result == 0) wlog ("# %d chars exported\n", string::length (d));
    else
    {
        wlog ("# Export to string failed with error %d\n", result);
        return 0;
    }

    // Using export in an xml tree
    wlog ("", "Notes of current document\n");
    tree = xmlquery::parse (string::get (d));
    xmlquery::send (tree, "select title, id node notes.note orderby title");
    xmlquery::output (tree, kString, title, 511);
    xmlquery::output (tree, kInt, &id);
    xmlquery::exec (tree);
    while (xmlquery::fetch (tree))
    {
        wlog ("", "\t%s : %d\n", title, id);
    }
    xmlquery::close (tree);

    // Internal usage of export
    s = alloc (string::length (s)+1);
    strcpy (s, string::get (d));

    wlog ("", "\n\n");
    wlog ("", s);
    wlog ("", "\n\n");

    release (s);
    release (d);

    return 0;
}

Version 3.0 R1335, 8. May 2009

priint:comet InDesign® Plug-Ins, comet_pdf

document::notes::import
string
string::alloc

static int document::notes::import(
  ItemRef docRef = 0,
  char* srcPath = 0,
  char* srcString = 0,
  int flags = 6)

Import Comet notes into an InDesign® document. Comet notes are give as XML file or as a string containing the XML data of the Comet notes. You must have ToDoList installed.

Here you can find information about the used XML format

Please take care on the installation hints for importing end exporting PDF comments

Name Type Default Description
Return int   \ URL[error code]{../errorcodes.html} or 0
docRef ItemRef 0 Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
srcPath String or char* "" Source file

0 or "" : Ask for XML file. Ignored, if srcString is not 0

"pdf" : Import of PDF comments from the PDF next to document

Complete path of PDF: Import of PDF comments from this PDF
srcString String or char* 0 XML data for Comet notes to be imported. If empty, srcPath is taken.
flags int kUseDocumentPath + kReplaceNotes Import flags

0 : no more information
kUseDocumentPath : Search for import in the same folder as the document
kReplaceNotes : Remove all existing notes before importing.
kSuppressExternalUpdate : [InDesign® Server only] Notes imported by InDesign® Server are hidden by default. If you open the document using InDesign® (Desktop) later, these notes become visible by default. Suppress this behavior by setting the flag kSuppressExternalUpdate. Later calls to import_notes can override this setting.
#include "internal/types.h"

Replace all notes by the notes given in xxx.xml, while xxx is the documents name. 

int main ()
{
    document::import_notes ();
    return 0;
}

You can use a trick to remove all Comet Notes from a document: Use an empty string (but not 0) with the option kReplaceNotes as the import source. 

int main ()
{
    document::import_notes (0, 0, "");
    return 0;
}

[InDesign® Server] Import some notes into a document and export the document and all its notes to a PDF. If someone opens the document using InDesign® Desktop later, the notes should be invisible. 

#include "internal/types.h"

int main ()
{
    int			flags	= kUseDocumentPath + kReplaceNotes;

    flags += kSuppressExternalUpdate;
    document::import_notes (0, "$DESKTOP/foo.xml", "", flags);
    document::show_notes ();
    document::pdf_export(0, 0, "Druckbare Notizen");
    document::hide_notes (0);

    return 0;
}

Version 3.0 R1335, 8. Mai 2009
kSuppressExternalUpdate seit v3.3 R2812, 5. March 2012

priint:comet InDesign® Plug-Ins, comet_pdf

document::notes::export_
document::pdf_export
PDF comments

static int document::notes::show(ItemRef docRef = 0)

Show all Comet notes of a given document. Hidden Comet notes to non existing destinations are removed from the document by default.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef 0 Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)

Version 3.0 R1335, 8. May 2009

priint:comet InDesign® Plug-Ins

document::notes::import
document::notes::export_
document::notes::hide

static int document::notes::hide(ItemRef docRef = 0)

Hide all Comet notes of a given document.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef 0 Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)

Version 3.0 R1335, 8. May 2009

priint:comet InDesign® Plug-Ins

document::notes::import
document::notes::export_
document::notes::show

static int document::notes::get_printable(ItemRef docRef = 0)

Printability* of Comet notes.

*) "Printability" means printing and PFD exports.

Name Type Default Description
Return int   Comet notes printable?
1 : yes
0 : no
docRef ItemRef 0 Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)

Comet_pdf ignores the document and returns the value of the programm option --annot instead.

v3.3 R2792, 8. Feb. 2012

priint:comet InDesign® Plug-Ins, comet_pdf (since R23234, 7. Jun 2018)

static int document::notes::set_printable(ItemRef docRef = 0, int newState = 0)

Set the printability* of Comet notes.

*) "Printability" means printing and PFD exports.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef 0 Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)

Comet_pdf ignores the document and changes the value of the programm option --annot instead.

newState int 0 Printability
0 : Do not print or export to PDF
1 : Print and export to PDF

Toggle the print state of Comet notes. 

int main ()
{
    int 			printable	= document::get_notes_printable ();

    document::set_notes_printable (0, !printable);
    wlog ("", "# Note printable : %d\n", document::get_notes_printable ());

    return 0;
}

v3.3 R2792, 8. Feb. 2012

priint:comet InDesign® Plug-Ins, comet_pdf (since R23234, 7. Jun 2018)

frame::get_printable
frame::set_printable

static int document::notes::set_pdf_prefs(
  float fontSize = 12.0,
  char* fontFamily = "Verdana",
  int printable = 0,
  int opened = 1)

Default setting for PDF comments. See here for information about PDF export and import of Comet Notes

Name Type Default Description
Return int   0
fontSize int 12 Default font size for Comet Notes without local font size settings
fontfamily char* oder String "Verdana" Default font for Comet Notes without local font size settings
printable int 0 Make PDF comments printable?

0 : No
1 : Yes
opened int 1 Open PDF comments in viewer?

0 : No
1 : Yes

v4.1, R23456, 14. Jul 2018

priint:comet InDesign® Plug-Ins, comet_pdf

document::pdf_export
PDF-Export und -Import von Comet-Notizen

static int document::notes::change_group(
  ItemRef docRef,
  int oldGroupID,
  int newGroupID)

Transfer Comet Notes from one Comet Group to another Comet Group.

The function was called notes::cometgroup_changed until v4.2 R32064. This old name is still valid.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
oldGroupID int - ID of old Comet group
newGroupID int - ID of new Comet group

Create a new Comet Group from the current frame selection and transfer the Comet Notes of an already existing Comet Group to the new group. After that the old Comet Group can be deleted. 

int main ()
{
    int				groupID		= 24991; // Put in your Comet Group ID here.
    ItemList		oldGroup	= itemlist::get_cometgroup_members (0, groupID, 1);
    ItemList		newGroup	= itemlist::selected ();

    if (gRun > 1)	return 0;
    itemlist::create_cometgroup (newGroup);
    document::notes::change_group (0, groupID, itemlist::get_cometgroup (newGroup));

    itemlist::remove_items (oldGroup);

    return 0;
}

v3.3 R3827, 6. June 2013

priint:comet InDesign® Plug-Ins

notes::delete_groupnotes

static int document::notes::delete_groupnotes(ItemRef docRef, int groupID)

Delete the Groups notes of a Comet Group.

The function was called notes::cometgroup_deleted until v4.2 R32064. This old name is still valid.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
groupID int - ID of Comet group

v3.3 R3827, 6. June 2013

priint:comet InDesign® Plug-Ins

notes::change_group

static List document::notes::find(
  ItemRef docRef,
  char* selector,
  char* regex,
  ...)

Find Comet Notes.

The function returns a list of note IDs, which for example can be used in functions such as document::notes::delete_note

Search criteria can be passed using an arbitrary number of key value pairs. As keys, any of the selectors listed below can be used, the search value is evaluated as a regular expression.

"title", "A note" finds all notes, whose title contain the phrase "A note".

But "title", "^A note$" finds all notes, whose title is exactly "A note".

To edit notes directly by their document frames or references, use the functions itemlist::doc_notes, ... and frame::notes::change_dest, ... .

Name Type Default Description
Return List   List of note IDs matching the given search criteria
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
selector char * - identifier for the note field resp. property. Possible values:
  • "title": title of the note
  • "plain": plain text of any of the notes comments
  • "tagged": tagged text of any of the notes comments
  • "comment": plain or tagged text of any of the notes comments
  • "id": ID of the note
  • "type": type of the note
  • "customerID": customer ID
  • "customerID2": customer ID2
  • "customerID3": customer ID3
  • "customerStringID": customer StringID
  • "customerData1": customer value
  • "customerData2": customer value 2
  • "parentUIDs.frame": UID of the note frame
  • "parentUIDs.group": UID of the note group
  • "parentUIDs.page": UID of the note page
  • "parentUIDs.spread": UID of the note spread
  • "parentIDs.frame": ID of the note page
  • "parentIDs.group": ID of the note group
  • "parentIDs.page": page index of the note
  • "parentIDs.spread": spread index of the note
  • "created.user": created user
  • "created.role": role of the user created this note
  • "created.on": date of creation
  • "reponsible.user": responsible user
  • "responsible.role": role of the responsible user
  • "responsible.on": date of changing responsibility
  • "changed.user": changing user
  • "changed.role": role of the changing user
  • "changed.on": date of change
  • "changed.status": state after
regex char * - search pattern (regular expression)
... char * - further selector / regular expression pairs. Search criteria is linked with logical AND

v4.1.6 R25450

priint:comet InDesign® Plug-Ins

document::notes::show_note et al.
itemlist::doc_notes et al.
frame::note::get_dest et al.

static int document::notes::show_note(
  ItemRef docRef,
  int noteId,
  ...)

Show particular Comet Notes.

The notes are defined by their IDs (siehe document::notes::find). To edit notes directly by their document frames or references, use the functions itemlist::doc_notes, ... and frame::notes::change_dest, ... .

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
noteId int - ID of the note to be shown
... int - IDs of further notes to be shown

v4.1.6 R25450

priint:comet InDesign® Plug-Ins

document::notes::find
itemlist::doc_notes et al.
frame::note::get_dest et al.

static int document::notes::hide_note(
  ItemRef docRef,
  int noteId,
  ...)

Hide particular Comet Notes.

The notes are defined by their IDs (siehe document::notes::find). To edit notes directly by their document frames or references, use the functions itemlist::doc_notes, ... and frame::notes::change_dest, ... .

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
noteId int - ID of the note to be hidden
... int - IDs of further notes to be hidden

v4.1.6 R25450

priint:comet InDesign® Plug-Ins

document::notes::find
itemlist::doc_notes et al.
frame::note::get_dest et al.

static int document::notes::delete_note(
  ItemRef docRef,
  int noteId,
  ...)

Delete particular Comet Notes.

The notes are defined by their IDs (siehe document::notes::find). To edit notes directly by their document frames or references, use the functions itemlist::doc_notes, ... and frame::notes::change_dest, ... .

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
noteId int - ID of the note to be deleted
... int - IDs of further notes to be deleted

v4.1.6 R25450

priint:comet InDesign® Plug-Ins

document::notes::find
itemlist::doc_notes et al.
frame::note::get_dest et al.

static int document::sync::create_variant(
  ItemRef docRef,
  char* outfileInfo = 0,
  int flags = 1)

Create a variant of a sample document. This command is only useful for subsequent document synchronizations.

The command is not executable for new, unsaved documents!

The following steps are performed for the variant:

  1. All document pages are marked as dependent of the pages of the master document, see Javascript command doc.pageSetOrigin.
  2. All frames of the document are marked as dependent of the corresponding frames of the master document, see frame::set_origin.
  3. The XML root element priint_syncDocType is set to the value variant.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef 0 Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front) The command is not executable for new, unsaved documents!
outfileInfo char * oder String 0 Path hints for the variant

0 or "" : Place the variant with the suffix _variant next to the master document.

relative path : Place the variant under the specified name next to the master document. The name is given without the ending .indd.

otherwise : Complete path of the variant
flags int 1 Flags

1 : Existing variant may be overwritten

You can find a complete example in the description of the Document Synchronization: 

Example Script

v4.1.6 R26001, 30. Sep 2019

priint:comet InDesign® Plug-Ins

static int document::sync::possible(ItemRef variant, ItemRef master)

Check if a given document can be synchronized with another document. The following prerequisites must be fulfilled for a document synchronization:

Name Type Default Description
Return int   0 or ErrorCode
variant ItemRef - Document reference to the variant
0 : Current script document
master ItemRef - Document reference to the master

You can find a complete example in the description of the Document Synchronization: 

Example Script

v4.1.6 R26001, 30. Sep 2019

priint:comet InDesign® Plug-Ins

document::sync::create_variant, document::sync::before, document::sync::after, document::sync::swatches, document::sync::layers, document::sync::styles, document::sync::masterspreads
document::sync::groups
document::sync::remove_empty_pages document::sync::remove_empty_layers

static int document::sync::before(ItemRef variant)

Prepare a variant for synchronization with the master document. This step must be performed before every \URL[document synchronization]{../InDesign/Plugins/sync_documents.html!} At the end of the synchronization, the function document::sync::after must be executed.

The function sets the XML root element priint_syncDocType to the value in progress. This prevents changes to the variant from being registered as local changes that would prevent subsequent syncs.return int 0 or ErrorCode

Name Type Default Description
variant ItemRef - Document reference to the variant
0 : Current script document

You can find a complete example in the description of the Document Synchronization: 

Example Script

v4.1.6 R26001, 30. Sep 2019

priint:comet InDesign® Plug-Ins

document::sync::create_variant, document::sync::possible, document::sync::after

static int document::sync::after(ItemRef variant)

The synchronization of a variant is complete. Return the document to its normal state.return int 0 or ErrorCode

Name Type Default Description
variant ItemRef - Document reference to the variant
0 : Current script document

You can find a complete example in the description of the Document Synchronization: 

Example Script

v4.1.6 R26001, 30. Sep 2019

priint:comet InDesign® Plug-Ins

document::sync::create_variant, document::sync::possible, document::sync::before

static int document::sync::swatches(ItemRef variant, ItemRef master)

Synchronization of swatches. Create missing swatches, tinted swatches and gradient swatches in the variant and update swatches changed in the master in the variant too. Color groups are restored as needed. Shifts to other color groups in the variant are retained. The order of the swatches can change.

Name Type Default Description
Return int   0 or ErrorCode
variant ItemRef - Document reference to the variant
0 : Current script document
master ItemRef - Document reference to the master

You can find a complete example in the description of the Document Synchronization: 

Example Script

v4.1.6 R26001, 30. Sep 2019

priint:comet InDesign® Plug-Ins

document::sync::create_variant, document::sync::before, document::sync::after, document::sync::layers, document::sync::styles, document::sync::masterspreads, document::sync::pages
document::sync::groups, document::sync::remove_empty_pages document::sync::remove_empty_layers

static int document::sync::layers(ItemRef variant, ItemRef master)

Synchronization of layers. Create/update all layers of the master document into the variant. Layers are uniquely identified by their names. The order of the levels remains the same. layers newly added in the variant, which are not contained in the master, are added behind thier original layers form the master. If this layer does not exist (anymore), it is moved to the top.

Name Type Default Description
Return int   0 or ErrorCode
variant ItemRef - Document reference to the variant
0 : Current script document
master ItemRef - Document reference to the master

You can find a complete example in the description of the Document Synchronization: 

Example Script

v4.1.6 R26001, 30. Sep 2019

priint:comet InDesign® Plug-Ins

document::sync::create_variant, document::sync::before, document::sync::after, document::sync::swatches, document::sync::styles, document::sync::masterspreads, document::sync::pages
document::sync::groups, document::sync::remove_empty_pages document::sync::remove_empty_layers

static int document::sync::styles(ItemRef variant, ItemRef master)

Synchronization of style definitions. Create/update all styles of the master document in the variant. The command corresponds to the Javascript command doc.importStyles of the InDesign scripting DOM. The following styles are updated:

Name Type Default Description
Return int   0 or ErrorCode
variant ItemRef - Document reference to the variant
0 : Current script document
master ItemRef - Document reference to the master

You can find a complete example in the description of the Document Synchronization: 

Example Script

v4.1.6 R26001, 30. Sep 2019

priint:comet InDesign® Plug-Ins

document::sync::create_variant, document::sync::before, document::sync::after, document::sync::swatches, document::sync::layers, document::sync::masterspreads, document::sync::pages
document::sync::groups, document::sync::remove_empty_pages document::sync::remove_empty_layers

static int document::sync::masterspreads(ItemRef variant, ItemRef master)

Synchronization of master spreads. Create/update all master spreads of the master document in the variant. The command corresponds to the Javascript command doc.loadMasters of the InDesign scripting DOM.

Name Type Default Description
Return int   0 or ErrorCode
variant ItemRef - Document reference to the variant
0 : Current script document
master ItemRef - Document reference to the master

You can find a complete example in the description of the Document Synchronization: 

Example Script

v4.1.6 R26001, 30. Sep 2019

priint:comet InDesign® Plug-Ins

document::sync::create_variant, document::sync::before, document::sync::after, document::sync::swatches, document::sync::layers, document::sync::styles, document::sync::pages
document::sync::groups, document::sync::remove_empty_pages document::sync::remove_empty_layers

static int document::sync::pages(ItemRef variant, ItemRef master)

Synchronization of pages. Create/update (the settings) of all pages of the master document in the variant. The link to the original page in the master document is established via the information stored internally on the page (see Javascript function doc.pageGetOrigin.

Pages created locally in the variant (with an Origin == 0) are moved behind the original page. from the master. If this page does not (no longer) exist, the page is moved to the very back.

Name Type Default Description
Return int   0 or ErrorCode
variant ItemRef - Document reference to the variant
0 : Current script document
master ItemRef - Document reference to the master

You can find a complete example in the description of the Document Synchronization: 

Example Script

v4.1.6 R26001, 30. Sep 2019

priint:comet InDesign® Plug-Ins

document::sync::create_variant, document::sync::before, document::sync::after, document::sync::swatches, document::sync::layers, document::sync::styles, document::sync::masterspreads
document::sync::groups, document::sync::remove_empty_pages document::sync::remove_empty_layers

static int document::sync::groups(ItemRef variant, ItemRef master)

Synchronization of the frame groups. Create/update all frame groups as defined in in the master document. Groups of the master document have priority over groups of the variant.

Name Type Default Description
Return int   0 or ErrorCode
variant ItemRef - Document reference to the variant
0 : Current script document
master ItemRef - Document reference to the master

You can find a complete example in the description of the Document Synchronization: 

Example Script

v4.1.6 R26001, 30. Sep 2019

priint:comet InDesign® Plug-Ins

document::sync::create_variant, document::sync::before, document::sync::after, document::sync::swatches, document::sync::layers, document::sync::styles, document::sync::masterspreads
document::sync::pages, document::sync::remove_empty_pages document::sync::remove_empty_layers

static int document::sync::remove_empty_pages(ItemRef variant, ItemRef master)

Remove empty local pages. Delete all locally created and empty pages of the variant.

Since the variant may contain local changes, it is possible that a page that has been created in the master document is empty, but not in the variant. The variant can also have overridden master spread entries. Pages of the variant with local changes and/or eoverridden master spread entries will not be deleted!

Name Type Default Description
Return int   0 or ErrorCode
variant ItemRef - Document reference to the variant
0 : Current script document
master ItemRef - Document reference to the master

You can find a complete example in the description of the Document Synchronization: 

Example Script

v4.1.6 R26001, 30. Sep 2019

priint:comet InDesign® Plug-Ins

document::sync::create_variant, document::sync::before, document::sync::after, document::sync::swatches, document::sync::layers, document::sync::styles, document::sync::masterspreads, document::sync::pages
document::sync::groups, document::sync::remove_empty_layers

static int document::sync::remove_empty_layers(ItemRef variant, ItemRef master)

URL[Remove empyt local layers]{../InDesign/Plugins/sync_documents.html#remove_superflous_layers}. Delete all empty layers of the variant that were not created locally and are empty in the master document.

Since the variant may contain local changes, it is possible that a layer that has been created in the master document is empty, but not in the variant. The variant can also have overridden master spread entries. Layers of the variant with local changes and/or eoverridden master spread entries will not be deleted!

Name Type Default Description
Return int   0 or ErrorCode
variant ItemRef - Document reference to the variant
0 : Current script document
master ItemRef - Document reference to the master

You can find a complete example in the description of the Document Synchronization: 

Example Script

v4.1.6 R26001, 30. Sep 2019

priint:comet InDesign® Plug-Ins

document::sync::create_variant, document::sync::before, document::sync::after, document::sync::swatches, document::sync::layers, document::sync::styles, document::sync::masterspreads, document::sync::pages
document::sync::groups, document::sync::remove_empty_pages

static int document::sync::cleanup(ItemRef variant, ItemRef master)

Clean up the document after a /URL[synchronization]{../InDesign/Plugins/sync_documents.html}. In the current version, the function removes superflous gradients from object and paragraph styles.

Name Type Default Description
Return int   0 or ErrorCode
variant ItemRef - Dokumentreferenz der Variante
0 : aktuelles Skriptdokument
master ItemRef - Dokumentreferenz des Musterdokumentes

You can find a complete example in the description of the Document Synchronization: 

Example Script

v4.1.6 R26263, 11. Nov 2019

priint:comet InDesign® Plug-Ins

static int document::metadata::set_title(ItemRef docRef, char* value)

Set the document title. The document title is displayed in the InDesign File -> File Information... dialog and in the Acrobat menu File -> Properties... of the PDF.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
value char* oder String - New document title. The new value may be empty (0 or "").

v4.2 R32680, 4. Apr 2023

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CDocument.setMetaData

static char* document::metadata::get_title(ItemRef docRef)

Get the documents title. The documents title is displayed in the InDesign File -> File Information... dialog and in the Acrobat menu File -> Properties... of the PDF.

Name Type Default Description
Return char*   Title of document.

The return value must not be changed and will be overwritten in subsequent calls of the function. See here to learn more about functions returning r/o char* values.

docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)

v4.2 R32680, 4. Apr 2023

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CDocument.getMetaData

static int document::metadata::set_author(ItemRef docRef, char* value)

Set the author of the document. The author of the document is displayed in the InDesign File -> File Information... dialog and in the Acrobat menu File -> Properties... of the PDF.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
value char* oder String - New author of the document. The new value may be empty (0 or "").

v4.2 R32680, 4. Apr 2023

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CDocument.setMetaData

static char* document::metadata::get_author(ItemRef docRef)

Get the author of the document. The author of the document is displayed in the InDesign File -> File Information... dialog and in the Acrobat menu File -> Properties... of the PDF.

Name Type Default Description
Return char*   Author of the document

The return value must not be changed and will be overwritten in subsequent calls of the function. See here to learn more about functions returning r/o char* values.

docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)

v4.2 R32680, 4. Apr 2023

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CDocument.getMetaData

static int document::metadata::set_author_title(ItemRef docRef, char* value)

Set the title of the author of the document. The author of the document is displayed in the InDesign File -> File Information... dialog and in the Acrobat menu File -> Properties... of the PDF.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
value char* oder String - New title of the author of the document. The new value may be empty (0 or "").

v4.2 R32680, 4. Apr 2023

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CDocument.setMetaData

static char* document::metadata::get_author_title(ItemRef docRef)

Get the title of the documents author. The authors title is displayed in the InDesign File -> File Information... dialog and in the Acrobat menu File -> Properties... of the PDF.

Name Type Default Description
Return char*   Title of the documents author

The return value must not be changed and will be overwritten in subsequent calls of the function. See here to learn more about functions returning r/o char* values.

docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)

v4.2 R32680, 4. Apr 2023

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CDocument.getMetaData

static int document::metadata::set_author_descr(ItemRef docRef, char* value)

Set the document description of the author. The document description of the author is displayed in the InDesign File -> File Information... dialog and in the Acrobat menu File -> Properties... of the PDF.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
value char* oder String - New document description of the author of the document. The new value may be empty (0 or "").

v4.2 R32680, 4. Apr 2023

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CDocument.setMetaData

static char* document::metadata::get_author_descr(ItemRef docRef)

Get the document description of the author. The document description of the author is displayed in the InDesign File -> File Information... dialog and in the Acrobat menu File -> Properties... of the PDF.

Name Type Default Description
Return char*   Get the document description of the author

The return value must not be changed and will be overwritten in subsequent calls of the function. See here to learn more about functions returning r/o char* values.

docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)

v4.2 R32680, 4. Apr 2023

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CDocument.getMetaData

static int document::metadata::set_descr(ItemRef docRef, char* value)

Set the author of the document. The author of the document is displayed in the InDesign File -> File Information... dialog and in the Acrobat menu File -> Properties... of the PDF.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
value char* oder String - New author of the document. The new value may be empty (0 or "").

v4.2 R32680, 4. Apr 2023

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CDocument.setMetaData

static char* document::metadata::get_descr(ItemRef docRef)

Get the description of the document. The description of the document is displayed in the InDesign File -> File Information... dialog and in the Acrobat menu File -> Properties... of the PDF.

Name Type Default Description
Return char*   Description of the document.

The return value must not be changed and will be overwritten in subsequent calls of the function. See here to learn more about functions returning r/o char* values.

docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)

v4.2 R32680, 4. Apr 2023

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CDocument.getMetaData

static int document::metadata::set_keys(ItemRef docRef, char* value)

Define the keywords for the document. Multiple keywords can be separated by commas. The keywords for the document is displayed in the InDesign File -> File Information... dialog and in the Acrobat menu File -> Properties... of the PDF.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
value char* oder String - New keywords for the document. The new value may be empty (0 or "").

v4.2 R32680, 4. Apr 2023

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CDocument.setMetaData

static char* document::metadata::get_keys(ItemRef docRef)

Get the defined keywords of the document. Multiple keywords are be separated by commas. The keywords of the document are displayed in the InDesign File -> File Information... dialog and in the Acrobat menu File -> Properties... of the PDF.

Name Type Default Description
Return char*   Defined keywords of the document.

The return value must not be changed and will be overwritten in subsequent calls of the function. See here to learn more about functions returning r/o char* values.

docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)

v4.2 R32680, 4. Apr 2023

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CDocument.getMetaData

static int document::metadata::set_copyright(ItemRef docRef, char* value)

Define a Copyright note of the document. The Copyright note of the document is displayed in the InDesign File -> File Information... dialog and in the Acrobat menu File -> Properties... of the PDF.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
value char* oder String - Copyright note of the document. The new value may be empty (0 or "").

v4.2 R32680, 4. Apr 2023

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CDocument.setMetaData

static char* document::metadata::get_copyright(ItemRef docRef)

Get the copyright note of the document. The Copyright note of the document is displayed in the InDesign File -> File Information... dialog and in the Acrobat menu File -> Properties... of the PDF.

Name Type Default Description
Return char*   Copyright note of the document

The return value must not be changed and will be overwritten in subsequent calls of the function. See here to learn more about functions returning r/o char* values.

docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)

v4.2 R32680, 4. Apr 2023

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CDocument.getMetaData

static int document::metadata::set_copyright_url(ItemRef docRef, char* value)

Define the Copyright Info URL of the document.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Valid document reference

0 : Current document
value char* oder String - Copyright Info URL of the document. The new value may be empty (0 or ""). 
int main ()
{
    // rating
    //
    printf ("rating : %d\n", document::metadata::get_rating (0));
    document::metadata::set_rating (0, 2);
    printf ("rating : %d\n", document::metadata::get_rating (0));

    // copyright_url
    //
    printf ("copyright_url : '%s'\n", document::metadata::get_copyright_url (0));
    document::metadata::set_copyright_url (0, "www.bahn.deppfff");
    printf ("copyright_url : '%s'\n", document::metadata::get_copyright_url (0));

    // copyright_state
    //
    printf ("copyright_state : %d\n", document::metadata::get_copyright_state (0));
    document::metadata::set_copyright_state (0, 2);
    printf ("copyright_state : %d\n", document::metadata::get_copyright_state (0));

    return 0;
}

v4.2 R32777, 26. Apr 2023

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CDocument.setMetaData

static char* document::metadata::get_copyright_url(ItemRef docRef)

Get the Copyright Info URL of the document.

Name Type Default Description
Return char*   Copyright Info URLof the document

The return value must not be changed and will be overwritten in subsequent calls of the function. See here to learn more about functions returning r/o char* values.

docRef ItemRef - Valid document reference

0 : Current document 
int main ()
{
    // rating
    //
    printf ("rating : %d\n", document::metadata::get_rating (0));
    document::metadata::set_rating (0, 2);
    printf ("rating : %d\n", document::metadata::get_rating (0));

    // copyright_url
    //
    printf ("copyright_url : '%s'\n", document::metadata::get_copyright_url (0));
    document::metadata::set_copyright_url (0, "www.bahn.deppfff");
    printf ("copyright_url : '%s'\n", document::metadata::get_copyright_url (0));

    // copyright_state
    //
    printf ("copyright_state : %d\n", document::metadata::get_copyright_state (0));
    document::metadata::set_copyright_state (0, 2);
    printf ("copyright_state : %d\n", document::metadata::get_copyright_state (0));

    return 0;
}

v4.2 R32777, 26. Apr 2023

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CDocument.getMetaData

static int document::metadata::set_copyright_state(ItemRef docRef, int value)

Define the Copyright-State of the document.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Valid document reference

0 : Current document
value int - Copyright-State of the document.

1 : Copyright protected
2 : Public Domain
otherwise : Unknown 
int main ()
{
    // rating
    //
    printf ("rating : %d\n", document::metadata::get_rating (0));
    document::metadata::set_rating (0, 2);
    printf ("rating : %d\n", document::metadata::get_rating (0));

    // copyright_url
    //
    printf ("copyright_url : '%s'\n", document::metadata::get_copyright_url (0));
    document::metadata::set_copyright_url (0, "www.bahn.deppfff");
    printf ("copyright_url : '%s'\n", document::metadata::get_copyright_url (0));

    // copyright_state
    //
    printf ("copyright_state : %d\n", document::metadata::get_copyright_state (0));
    document::metadata::set_copyright_state (0, 2);
    printf ("copyright_state : %d\n", document::metadata::get_copyright_state (0));

    return 0;
}

v4.2 R32777, 26. Apr 2023

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CDocument.setMetaData

static int document::metadata::get_copyright_state(ItemRef docRef)

Get the Copyright-State of the document.

Name Type Default Description
Return int   Copyright-Stateof the document

0 : Unknown
1: Copyright protected
2 : Public Domain
-1 : Error
docRef ItemRef - Valid document reference

0 : Current document 
int main ()
{
    // rating
    //
    printf ("rating : %d\n", document::metadata::get_rating (0));
    document::metadata::set_rating (0, 2);
    printf ("rating : %d\n", document::metadata::get_rating (0));

    // copyright_url
    //
    printf ("copyright_url : '%s'\n", document::metadata::get_copyright_url (0));
    document::metadata::set_copyright_url (0, "www.bahn.deppfff");
    printf ("copyright_url : '%s'\n", document::metadata::get_copyright_url (0));

    // copyright_state
    //
    printf ("copyright_state : %d\n", document::metadata::get_copyright_state (0));
    document::metadata::set_copyright_state (0, 2);
    printf ("copyright_state : %d\n", document::metadata::get_copyright_state (0));

    return 0;
}

v4.2 R32777, 26. Apr 2023

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CDocument.getMetaData

static int document::metadata::set_rating(ItemRef docRef, int value)

Define the Rating of the document.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Valid document reference

0 : Current document
value int - Rating of the document.

1 - 5 : Number of stars
otherwise : No rating 
int main ()
{
    // rating
    //
    printf ("rating : %d\n", document::metadata::get_rating (0));
    document::metadata::set_rating (0, 2);
    printf ("rating : %d\n", document::metadata::get_rating (0));

    // copyright_url
    //
    printf ("copyright_url : '%s'\n", document::metadata::get_copyright_url (0));
    document::metadata::set_copyright_url (0, "www.bahn.deppfff");
    printf ("copyright_url : '%s'\n", document::metadata::get_copyright_url (0));

    // copyright_state
    //
    printf ("copyright_state : %d\n", document::metadata::get_copyright_state (0));
    document::metadata::set_copyright_state (0, 2);
    printf ("copyright_state : %d\n", document::metadata::get_copyright_state (0));

    return 0;
}

v4.2 R32777, 26. Apr 2023

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CDocument.setMetaData

static ItemList document::get_articles(ItemRef docRef = 0)

Get a list of all articles in a document. The function is equivalent to the function itemlist::articles.

The articles in a document can also be edited manually using the Articles panel.

Name Type Default Description
Return ItemList   List of all articles in the document

The results list must be deleted again with itemlist::release!

docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)

v5.0, R35050

priint:comet InDesign® Plug-Ins, comet_pdf
document::articles::count
document::articles::get_nth
comet.CDocument.getArticles

static int document::articles::count(ItemRef docRef = 0)

How many articles are in a given document?

Name Type Default Description
Return int   Number of articles in the document.
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)

Loop over all articles in a document. 

int main ()
{
    int 	i;
    ItemRef	fa		= item::alloc ();

    for (i = 0; i < document::articles::count (); i++)
    {
        document::articles::get_nth (0, fa, i);

        wlog ("", "# %d (UID %d)	: %s, (use for export : %d)\n",
         			i + 1,
         			item::getint (fa),
         			document::article::get_name (fa),
         			document::article::get_use_for_export (fa));
    }

    item::release (fa);

    return 0;
}

Alternatively (and a bit faster), you can also run this loop as usual via the ItemList of articles. 

int main ()
{
    int 		i;
    ItemList	articles;
    ItemRef		fa		= item::alloc ();

    articles	= itemlist::articles ();
    for (i = 0; i < itemlist::length (articles); i++)
    {
        itemlist::get (articles, fa, i);

        wlog ("", "# %d (UID %d)	: %s, (use for export : %d)\n",
         			i + 1,
         			item::getint (fa),
         			document::article::get_name (fa),
         			document::article::get_use_for_export (fa));
    }

    item::release (fa);
    itemlist::release (articles);

    return 0;
}

v5.0, R35050

priint:comet InDesign® Plug-Ins, comet_pdf
itemlist::articles
document::articles::get_nth

static int document::articles::get_nth(
  ItemRef docRef,
  ItemRef outArticleRef,
  int nth)

Get the nth article of a document.

Name Type Default Description
Return int   0 : Article found
Otherwise : Error Code
docRef ItemRef - Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
outArticleRef ItemRef - Return variable for the article found.

0 : Ignore result
Otherwise : Allocated variable of type ItemRef
nth int - 0-based index of the article. If nth ≥ articles::count, the function returns an error.

-1 : Last article

v5.0, R35050

priint:comet InDesign® Plug-Ins, comet_pdf
document::articles::count
itemlist::articles

static int document::articles::find(ItemRef frameRef)

Create a list of all articles in a document that contain a specific frame.

One and the same frame can be assigned to several articles at the same time. For the desired accessibility this is certainly not particularly helpful.

Name Type Default Description
Return ItemList   List of all articles in the document that contain the given frame.

The results list must be deleted again with itemlist::release!

frameRef ItemRef 0 Valid frame reference

0 : Current script frame

Collect all articles that contain the current script frame. 

int main ()
{
    int 		i;
    ItemList	articles;
    ItemRef		fa		= item::alloc ();

    articles	= document::articles::find (gFrame);
    for (i = 0; i < itemlist::length (articles); i++)
    {
        itemlist::get (articles, fa, i);

        wlog ("", "# %d (UID %d)	: %s, (use for export : %d)\n",
        i + 1,
        item::getint (fa),
        document::article::get_name (fa),
        document::article::get_use_for_export (fa));
    }

    item::release (fa);
    itemlist::release (articles);

    return 0;
}

v5.0, R35050

priint:comet InDesign® Plug-Ins, comet_pdf
document::articles::count
itemlist::articles
comet.CPageItem.getArticles

static int document::article::create(
  ItemRef outArticleRef = 0,
  ItemRef docRef = 0,
  char* name = 0,
  int pos = -1,
  int useForExport = 1)

Create a new empty article in the specified document.

Name Type Default Description
Return int   0 or ErrorCode
outArticleRef ItemRef 0 If successfully executed, the variable contains a valid reference to the new article.

0 : Ignore result
Otherwise : Allocated variable of type ItemRef
docRef ItemRef 0 Document specification

gDocument or 0: Document with which the script was started.

Otherwise: Valid document reference (e.g. from document::get_front)
name char* or String 0 Name of the new article

0 oder "" : Use standard name
pos int -1 Position in the article list

-1 : Append
> 0 : 0-based index
useForExport int 1 Should the article be exported?

1 : Yes
0 : No

v5.0, R35050

priint:comet InDesign® Plug-Ins, comet_pdf
document::articles::count
itemlist::articles
comet.CDocument.createArticle

static int document::article::remove(ItemRef articleRef)

Delete an article. The content of the article is retained.

Name Type Default Description
Return int   0 or ErrorCode
articleRef ItemRef - Valid reference to an article

v5.0, R35050

priint:comet InDesign® Plug-Ins, comet_pdf
document::articles::count
itemlist::articles
comet.CArticle.remove

static int document::article::set_pos(ItemRef articleRef, int pos = -1)

Move an article in the article list.

Name Type Default Description
Return int   0 or ErrorCode
articleRef ItemRef - Valid reference to an article
pos int -1 New position of the article in the article list

-1 : To the end

v5.0, R35050

priint:comet InDesign® Plug-Ins, comet_pdf
document::articles::count
itemlist::articles
comet.CArticle.setIndex

static int document::article::get_pos(ItemRef articleRef)

Determine the position of an article within the articles list.

Name Type Default Description
Return int   0 or ErrorCode
articleRef ItemRef - Valid reference to an article

v5.0, R35050

priint:comet InDesign® Plug-Ins, comet_pdf
document::article::set_pos
document::articles::count
itemlist::articles
comet.CArticle.getIndex

static char* document::article::get_name(ItemRef articleRef)

Determine the name of an article within the articles list.

Name Type Default Description
Return int   Name of requeseted article

The return value must not be changed and will be overwritten in subsequent calls of the function. See here to learn more about functions returning r/o char* values.

"": Error
articleRef ItemRef - Valid reference to an article

v5.0, R35050

priint:comet InDesign® Plug-Ins, comet_pdf
document::article::set_name
document::articles::count
itemlist::articles
comet.CArticle.getName

static int document::article::set_name(ItemRef articleRef)

Change the name of an article within the articles list. To manually change an article, click or double-click the article directly in the Articles panel.

Name Type Default Description
Return int   0 or ErrorCode
articleRef ItemRef - Valid reference to an article
name char* oder String 0 New name for the article

0 or "" : Use standard name

v5.0, R35050

priint:comet InDesign® Plug-Ins, comet_pdf
document::article::get_name
document::articles::count
itemlist::articles
comet.CArticle.setName

static int document::article::get_use_for_export(ItemRef articleRef)

Is the article included to the accessibility tags of the document export? The function queries the article setting Include when exporting, which is shown when an article is double-clicked in the Articles panel.

Name Type Default Description
Return int   0 : No
1 : Yes
-1 : Error
articleRef ItemRef - Valid reference to an article

v5.0, R35050

priint:comet InDesign® Plug-Ins, comet_pdf
document::article::set_use_for_export
document::articles::count
itemlist::articles
comet.CArticle.getUseForExport

static int document::article::set_use_for_export(ItemRef articleRef, int useFoExport)

Should the article be included into the export? The function sets the Article setting Include When Exporting, which can be set manually when an article is double-clicked in the Articles panel.

Name Type Default Description
Return int   0 or ErrorCode
articleRef ItemRef - Valid reference to an article
useFoExport int - 0 : No, do not use
1 : Yes

v5.0, R35050

priint:comet InDesign® Plug-Ins, comet_pdf
document::article::get_use_for_export
document::articles::count
itemlist::articles

static ItemList document::article::get_members(ItemRef articleRef)

Create a list of all elements (members) of an article. The list usually contains the document frames whose contents form the article.

Name Type Default Description
Return ItemList   List of all frames of the article

The results list must be deleted again with itemlist::release!

articleRef ItemRef - Valid reference to an article

v5.0, R35050

priint:comet InDesign® Plug-Ins, comet_pdf
document::articles::count
itemlist::articles
comet.CArticle.getMembers

static int document::article::members::add(ItemRef articleRef, ItemRef frameRef = 0; int pos = -1)

Add a member (a frame) to an article.

Name Type Default Description
Return int   0 or ErrorCode
articleRef ItemRef - Valid reference to an article
frameRef ItemRef 0 Valid frame reference

0 : Current script frame
pos int -1 0-based index of the new member in the members list of the article

-1 : Append

Add the current script frame to the end of the last article of the document. 

int main ()
{
    ItemRef		fa		= item::alloc ();

    document::articles::get_nth (0, fa, -1);
    document::article::members::add (fa, gFrame);
    item::release (fa);

    return 0;
}

v5.0, R35050

priint:comet InDesign® Plug-Ins, comet_pdf
itemlist::articles
document::article::get_members
comet.CArticle.addMembers

static int document::article::members::add_multi(
  ItemRef articleRef,
  int uid,
  ...)

Add any number of members (frames) to an article.

Name Type Default Description
Return int   0 or Error Code

-1 or 1 : General error

> 0: At least one frame from the specified list could not be added to the members list. The return value is the first UID that was not inserted. Regardless of this, all existing frames are still added to the members list.
articleRef ItemRef - Valid reference to an article
uid, ... int, ... - Any number of frame UIDs, terminated by the insertion position in the members list of the article. Non-existent frames are ignored.

..., -1 : Add members
..., N : : Insert members at the 0-based position N

The final position specification is mandatory and must also be specified for 'Append' (-1)!

If frames 1000-1003 exist but 999999 not, the frames 1000-1003 are added to the member list. Frame 999999 is ignored and the function returns 999999. 

1000, 1001, 999999, 1002, 1003, -1

Add some frames to the end of the last article of the document. 

int main ()
{
    ItemRef		fa		= item::alloc ();

    document::articles::get_nth (0, fa, -1);
    document::article::members::add_multi (fa, 1000, 1001, 999999, 1002, 1003, -1);
    item::release (fa);

    return 0;
}

v5.0, R35050

priint:comet InDesign® Plug-Ins, comet_pdf
itemlist::articles
document::article::get_members
comet.CArticle.addMembers

static int document::article::member::remove(ItemRef articleRef, ItemRef frameRef = 0)

Remove a frame from an article. The frame itself is not deleted.

Name Type Default Description
Return int   0 or ErrorCode
articleRef ItemRef - Valid reference to an article
frameRef ItemRef 0 Valid frame reference

0 : Current script frame

v5.0, R35050

priint:comet InDesign® Plug-Ins, comet_pdf
itemlist::articles
document::article::get_members
comet.CArticle.removeMembers

static int document::article::member::get_pos(ItemRef articleRef, ItemRef frameRef = 0)

Determine the position of a frame in an article.

Name Type Default Description
Return int   0 or ErrorCode
articleRef ItemRef - Valid reference to an article
frameRef ItemRef 0 Valid frame reference

0 : Current script frame

v5.0, R35050

priint:comet InDesign® Plug-Ins, comet_pdf
document::article::get_members
document::article::members::set_pos
itemlist::articles
comet.CArticle.getMemberIndex

static int document::article::member::set_pos()

Move frame inside the members list of an article.

Name Type Default Description
Return int   0 or ErrorCode
articleRef ItemRef - Valid reference to an article
frameRef ItemRef 0 Valid frame reference

0 : Current script frame
pos int -1 0-based index of the new member in the members list of the article

-1 : Append

v5.0, R35050

priint:comet InDesign® Plug-Ins, comet_pdf
itemlist::articles
document::article::get_members
comet.CArticle.setMemberIndex

Since
Plugin Version 1.0.14
Version
24.04.2025, 13:54 Uhr
Author
Paul Seidel

Alphabetic index HTML hierarchy of classes or Java