Document methods.

Document methods.

static ItemRef 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.

int main ()
{
    ItemRef			d1		= document::alloc ("$DESKTOP/test.indd");
    ItemRef			d2		= document::alloc ("Unnamed-1");
    wlog ("", "Test	: %d\n", item::getint (d1));
    wlog ("", "New	: %d\n", item::getint (d2));
    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;
}

Since

v3.3 R2851, 12.04.2012

Available

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

static int 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

Since

Version 1.4.1 R383, 28. June 2007

Available

priint:comet InDesign^® Plug-Ins, Illustrator

See Also

item::defined

static ItemRef 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

Since

Version 1.1.7, Januar 2005

Available

priint:comet InDesign^® Plug-Ins, Illustrator

See Also

document::get_front
document::select

static ItemRef get_front()

Get the front document.

Name	Type	Default	Description
Return	ItemRef		Reference to the front document. Release this reference as soon as possible using item::release.

Since

Version 2.1 R1800, 15. March 2010

Available

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

See Also

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

static int count()

How many documents are open in the moment?

Name	Type	Default	Description
Return	int		Number of open documents

Since

v3.3 R2851, 12. Apr 2012

Available

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

See Also

comet.document.getOpen

static char* 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

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

Since

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

Available

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

See Also

comet.document.getOpen

static int 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)

Since

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

Available

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

See Also

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

static int 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

Since

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

Available

priint:comet InDesign^® Plug-Ins

See Also

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

static ItemRef 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)

Preconditions

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

Since

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

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

static ItemRef 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

Preconditions

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

Since

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

Available

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

See Also

comet.document.open

static ItemRef 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

Preconditions

#include "internal/types.h"

Since

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

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

static int 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

@since Version 4.0.5 R8202, 17. June 2015

Available

priint:comet InDesign^® Plug-Ins

See Also

get_display_name
comet.CDocument.setDisplayName

static char* 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)

Since

v4.1.8 R27600, 7. Okt. 2020

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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

static int 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);

Since

docRef seit Version 2.1 R1800, 15. March 2010

Available

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

static int 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.

Preconditions

#include "internal/types.h"

Since

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

Available

priint:comet InDesign^® Plug-Ins, Illustrator

See Also

comet.CDocument.close

static int 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.

Preconditions

#include "internal/types.h"

Since

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

Available

priint:comet InDesign^® Plug-Ins

static int 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.

Preconditions

#include "internal/types.h"

Since

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

Available

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

See Also

comet.CDocument.save

static int 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.

Preconditions

#include "internal/types.h"

Since

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

Available

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

See Also

comet.CDocument.saveAs

static int 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)

Since

v4.0.5 R10000, 5. Feb 2015

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

static char* 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));

Since

The parameter doc is valid from version 1.1.7, Januar 2005

Available

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

See Also

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

static char* 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));

Since

The parameter doc is valid from version 1.1.7, Januar 2005

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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

static char* 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));

Since

The parameter doc is valid from version 1.1.7, January 2005

Available

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

See Also

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

static char* 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));

Since

The parameter doc is valid from version 1.1.7 January 2005

Available

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

See Also

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

static char* 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));

Since

The parameter doc is valid from version 1.1.7 January 2005

Available

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

See Also

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

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

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

Deprecated

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

static int 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)

Since

Parameter doc since Version 1.1.7, Januar 2005 v1.2

Available

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

See Also

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

static int 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)

p = document::page ();

Since

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

Available

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

See Also

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

static char* 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));

Since

Version 1.2.2 (24. November 2005)

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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

static int 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"

Since

Version 1.2.2 (24. November 2005)

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

document::end_sequence
document::build_products

static int 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

Since

Version 1.2.2 (24. November 2005)

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

document::begin_sequence

static int open_sequence(char* name = 0)

DEPRECATED! Please use the function document::begin_sequence instead.

Name	Type	Default	Description
Return	int		0 or ErrorCode

Deprecated

Please use the function document::begin_sequence instead.

static int purge_sequence()

DEPRECATED! Please use the function document::begin_sequence instead.

Name	Type	Default	Description
Return	int		0 or ErrorCode

Deprecated

Please use the function document::begin_sequence instead.

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

DEPRECATED! Please use the function document::begin_sequence instead.

Name	Type	Default	Description
Return	int		0 or ErrorCode

Deprecated

Please use the function document::begin_sequence instead.

static int 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]]);

Since

appendToRecent since Version 2.1 R1650, 11.11.2009

Available

priint:comet InDesign^® Plug-Ins

See Also

document::store_macro

static int repaint()

DEPRECATED! Update the presentation of the complete document.

Deprecated

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

Since

1.0.19

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

static int 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);

Since

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

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

comet.CDocument.setStartPage

static int 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]]);

Since

v1.2

Available

priint:comet InDesign^® Plug-Ins

See Also

document::load
document::insert_macro

static ItemList 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]]]);

Since

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

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

document::store_macro
pages
layer

static ItemList 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.

Preconditions

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

Since

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

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

document::store_macro
document::place_indesign
pages
layer

static ItemList 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.

Since

Version 4.1.7 R26766, April 2020

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

document::place_items
document::place_indesign

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

Since

Version 2.1 R 1800, 14. March 2010

Available

priint:comet InDesign^® Plug-Ins

See Also

document::place_items
pages
layer

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

Since

sid since Version 1.3 (Build 96)

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

Parameter diveInto since v4.0.5 R11012

static int 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);

Since

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

Available

priint:comet InDesign^® Plug-Ins

See Also

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

static int 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;) vailable 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';)

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 (print) with the given profile "" or 0 : PDF (Print) with the current PDF export options for PDF (Print)
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.

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

Since

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

Available

priint:comet InDesign^® Plug-Ins, Illustrator

See Also

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

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

Since

Version 3.1 R 1819, 22.3.2010

Available

priint:comet InDesign^® Plug-Ins

static int 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

Preconditions

#include "internal/types.h"

Since

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

Available

priint:comet InDesign^® Plug-Ins

See Also

document::export_

static int 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

Since

Version 1.1.4

See Also

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

Available

priint:comet InDesign^® Plug-Ins
Illustrator

static int 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.

Since

v4.2 R33733, 3. Nov 2023

Available

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

See Also

textmodel::force_redraw
comet.CDocument.redraw

static int 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);

Since

Version 1.1.4

Available

priint:comet InDesign^® Plug-Ins

See Also

document::export_

static int 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 repositioned <0 : Reposition to above 0 : No repositioning to another page >0 : Reposition to below
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

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

Since

v3.0

Available

priint:comet InDesign^® Plug-Ins

static int 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.

Preconditions

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

Since

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

Available

priint:comet InDesign^® Plug-Ins

See Also

datapool::get_products
page::masteritems_load

static int 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)

Preconditions

#include "internal/types.h"

Since

Version 1.3.1 (19. Januar 2006)

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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

static int 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)

Preconditions

#include "internal/types.h"

Since

Version 1.3.1 (19 January 2006)

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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

static int 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

Since

Version 1.3.3 (P/R 59)

Available

priint:comet InDesign^® Plug-Ins

See Also

document::concat

static int 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

Since

Version 1.3.3 (P/R 59)

Available

priint:comet InDesign^® Plug-Ins

See Also

document::split

static int join(
  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

Deprecated

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

static int 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

Since

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

Available

priint:comet InDesign^® Plug-Ins

static int 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

Since

Version 1.4 (R 339), 2. Mai 2007

Available

priint:comet InDesign^® Plug-Ins

See Also

document::justify_text_reset
textmodel::justify

static int 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

Since

Version 1.4 (R 339), 2. Mai 2007

Available

priint:comet InDesign^® Plug-Ins

See Also

document::justify_text
textmodel::justify_reset

static int 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

Since

Version 1.4.1 R417, 24. Jul 2007

Available

priint:comet InDesign^® Plug-Ins

See Also

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

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

Since

Version 1.4.2 R491, 26. Oct 2007

Available

priint:comet InDesign^® Plug-Ins

static int 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>

Since

Version 1.4.2, R 504, 12. Nov. 2007

Available

priint:comet InDesign^® Plug-Ins

See Also

document::adapt

static int 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

Since

Version 1.4.2, R 504, 12. Nov. 2007

Available

priint:comet InDesign^® Plug-Ins

See Also

document::adapt_many

static int 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.

Since

Version 2.1, R 1090, 17. Dez. 2008

Available

priint:comet InDesign^® Plug-Ins

See Also

document::adapt
document::resize

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

Since

v4.2 R30710, 11. May 2022

Available

priint:comet InDesign^® Plug-Ins

See Also

document::stop_stamping

static int stop_stamping()

Finish stamping frames.

Name	Type	Default	Description
Return	int		0 or ErrorCode

Since

v4.2 R30710, 11. Mai 2022

Available

priint:comet InDesign^® Plug-Ins

See Also

document::start_stamping

static int 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.

Since

Version 2.1, R 1090, 17. Dez. 2008

Available

priint:comet InDesign^® Plug-Ins

See Also

document::adapt_self

static int 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

Since

Version 1.4.2 R 565, 12. Jan. 2008

Available

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

See Also

document::setid
comet.CDocument.getID

static int 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

Since

Version 1.4.2 R 565, 12. Jan. 2008

Available

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

See Also

document::setid
comet.CDocument.setID

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

Since

Version 2.1 R668, 9. April 2008

Available

priint:comet InDesign^® Plug-Ins

See Also

book
item
comet.CDocument.getBook

static int 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

Since

Version 2.1 R668, 10. April 2008

Available

priint:comet InDesign^® Plug-Ins

See Also

document::get_book

static int 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?

Since

Version 2.1 R1130, 22. Januar 2009

Available

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

See Also

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

static int 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?

Since

Version 2.1 R1130, 22. Januar 2009

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

document::get_bleed
document::set_slug

static int 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

Since

Version 2.1 R1130, 22. Januar 2009

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

document::get_bleed
set_slug
comet.CDocument.setBleed

static int 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

Since

Version 2.1 R1130, 22. Januar 2009

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

document::get_slug
document::set_bleed

static int 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.

Since

v3.3.1 R4100, 1. Aug 2013 and CS5

Available

priint:comet InDesign^® Plug-Ins

See Also

document::set_pasteboard_gutter

static int 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.)

Since

v3.3.1 R4100, 1. Aug 2013 and CS5

Available

priint:comet InDesign^® Plug-Ins

See Also

document::get_pasteboard_gutter

static int 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

Since

Version 3.0 R1155, 2. Feb. 2009

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

document::page_elements_shown

static int 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)

Since

Version 3.0 R1155, 2. Feb. 2009

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

document::show_page_elements

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

See document::notes::export_

See Also

document::notes::export_

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

See document::notes::import

See Also

document::notes::import

static int show_notes(ItemRef docRef = 0)

See document::notes::show

See Also

document::notes::show

static int hide_notes(ItemRef docRef = 0)

See document::notes::hide

See Also

document::notes::hide

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

Since

Version 2.1 R 1582, 5. Okt. 2009

Available

priint:comet InDesign^® Plug-Ins

See Also

document::get_default_style
textmodel::insert

static char* 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;
}

Since

Version 2.1 R 1582, 5. Okt. 2009

Available

priint:comet InDesign^® Plug-Ins

See Also

document::get_default_style
textmodel::insert

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

Since

Version 2.1 R1978, 27.06.2010

Available

priint:comet InDesign^® Plug-Ins

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

Since

Version 3.3 R2764, 14.12.2011

Available

priint:comet InDesign^® Plug-Ins, Illustrator

static int 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

Preconditions

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

Since

Version 3.1 R2187, 25. Okt. 2010

Available

priint:comet InDesign^® Plug-Ins

See Also

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

static int 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'

Preconditions

#include "internal/types.h"

Since

Version 3.1 R2187, 25. Okt. 2010

Available

priint:comet InDesign^® Plug-Ins

See Also

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

static float 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

Preconditions

#include "internal/types.h"

Since

Version 3.1 R2187, 25. Okt. 2010

Available

priint:comet InDesign^® Plug-Ins

See Also

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

static float 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)

Since

Version 3.1 R2187, 25. Okt. 2010

Available

priint:comet InDesign^® Plug-Ins

See Also

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

static float 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)

Since

Version 3.1 R2187, 25. Okt. 2010

Available

priint:comet InDesign^® Plug-Ins

See Also

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

static int 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 :

• Shape of frame, any shape is allowed.
• Image clip path, any path is allowed (kUseClippath)
• Holes inside the image clipping path (kAllowHoles)
• Frame overlapings (Z order). Frame transparency is ignored in this case).
• Page or page with margins (kUseMargins)

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).

Preconditions

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

Since

Version 3.2 R2210, 2. Dez. 2010

Available

priint:comet InDesign^® Plug-Ins

See Also

frame::get_visible_area
rectlist
floatlist
rect
idtype
idtypelist

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

Since

v3.3 R2550, 30.06.2011
Support for comet_pdf since v4.2 R32078, 28. Dec 2022

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

comet.CDocument.getDocLinks

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

Since

v3.3 R2489, 06.06.2011

Available

priint:comet InDesign^® Plug-Ins

static int 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

Since

v3.3 R2580, 1. Aug. 2011

Available

priint:comet InDesign^® Plug-Ins

static int 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 The list must be allocated with stringlist::alloc before using it! 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;
}

Since

v4.1 R24333, 6. Dez 2018

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

comet.CDocument.getStyleNames

static int 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);

Since

v4.1.6 R25778, 11. Sep. 2019
comet_pdf support since v4.1.8, R27723

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

static int 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)

Since

v3.3 R2670, 14. Okt. 2011 and InDesign^® CS5.5

Available

priint:comet InDesign^® Plug-Ins

static int get_notes_printable(ItemRef docRef = 0)

See Also

document::notes::get_printable

static int set_notes_printable(ItemRef docRef = 0, int newState = 0)

See Also

document::notes::set_printable

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

Since

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

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

comet.CDocument.getMasterPageInfo

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

Since

v3.3 R3091, 20.07.2012

Available

priint:comet InDesign^® Plug-Ins

Parameter openAsCopy since v4.1 R24334, 17. Dec 2018

See Also

import_masterpages

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

Since

v4.1.6 R25778, 16. Sep. 2019

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

import_masterpage

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

Since

v4.1.6 R25788, 16. Sep 2019

Available

priint:comet InDesign^® Plug-Ins

See Also

import_masterpages

static int 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

Since

v4.1.6 R25788, 16. Sep 2019

Available

priint:comet InDesign^® Plug-Ins

static int 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)

Since

v3.3 R3500, 07.03.2012

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

static int 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

Preconditions

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

Since

v3.3 R3500, 07.03.2012

Available

priint:comet InDesign^® Plug-Ins

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

Since

v3.3 R3500, 08.03.2012

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

comet.CPage.getUID

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

Since

v3.3 R3500, 08.03.2012

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

page::get_spread

static int 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.

Preconditions

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

Since

v4.0.4 R7740, 01 Apr 2015

Available

priint:comet InDesign^® Plug-Ins

static int 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

Preconditions

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

Since

v4.0.5 R8423

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

frame::write_frame_info
itemlist::write_frame_info
document::apply_frame_info

static int 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

Preconditions

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

Since

v4.0.5 R8423

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

frame::apply_frame_info
itemlist::apply_frame_info
document::write_frame_info

static int 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

Preconditions

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

Since

v4.0.5 R8423

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

frame::apply_frame_info
itemlist::apply_frame_info
document::write_frame_info

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

Since

v4.0.5 R9930

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

document::delete_frame_info

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

Since

v4.0.5 R10150

Available

priint:comet InDesign^® Plug-Ins

See Also

document::execute_missions
document::delete_missions
document::count_missions
document::remove_duplicate_missions

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

Since

v4.0.5 R10150

Available

priint:comet InDesign^® Plug-Ins

See Also

document::create_mission_ui
document::delete_missions
document::count_missions
document::remove_duplicate_missions

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

Since

v4.0.5 R10150

Available

priint:comet InDesign^® Plug-Ins

See Also

document::create_mission_ui
document::execute_missions
document::delete_missions
document::remove_duplicate_missions

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

Since

v4.0.5 R10102

Available

priint:comet InDesign^® Plug-Ins

See Also

document::create_mission_ui
document::execute_missions
document::count_missions
document::remove_duplicate_missions

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

Since

v4.0.5 R10102

Available

priint:comet InDesign^® Plug-Ins

See Also

document::create_mission_ui
document::execute_missions
document::count_missions
document::delete_missions

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

Since

Parameter behavior seit R20457, 13. Okt 2017 v4.0.4 R7740, 01 Apr 2015

Available

priint:comet InDesign^® Plug-Ins

static int link_with_unique_placeholder(
  ItemRef docRef,
  int placeholderID,
  int autoStore,
  int get_record_id_func,
  IDType recordID)

Synonym for prepare_translations.

See Also

document::prepare_translations

static int 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)

Since

v4.0.5 R9660, 19 Nov 2015

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

static int 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)

Since

v4.0.5 R9813, 8 Jan 2016

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

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

Since

v4.0.5 R9813, 8 Jan 2016

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

static int 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);

Since

Parameter maxlen sinc e v4.0.5 R14201, 13. Dez 2016
v4.0.5 R10224, 1. March 2016

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

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

Since

v4.0.5 R13799, 6. Oct 2016

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

static int 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

Since

v4.1.8 R30410, 18. Mar 2022

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

static int 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:

• The story scrap is created since 10 (!) years without creating any problems.
• Hundreds of thousands of such documents exist by now, of which we of course could only test a small fraction. Before cleaning your documents you should create backup copies!
• Before performing the cleanup as an automatic afterOpen action, you should put a sufficiently representative selection of documents through your workflow.

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)

Since

v4.0.5 R16180, 19. Mar 2017

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

static int 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

Since

v4.1 R21000, 16. Nov 2017

Available

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

static int 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!

Since

Version v4.1, 1. Oct 2018

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

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

Since

v4.0.5 R20002 (28. Jul 2017)

Available

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

See Also

frame::has_linked_url
itemlist::linked_urls

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

Since

v4.0.5 R20002 (28. Jul 2017)

Available

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

See Also

frame::has_embedded_url
itemlist::embedded_urls

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

Since

v4.0.5 R19777 (24. Jul 2017)

Available

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

See Also

frame::check_url_link
itemlist::check_url_links

static ItemList 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.

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

Since

v4.0.5 R20002 (28. Jul 2017)

Available

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

See Also

frame::update_url_link
itemlist::update_url_links

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

Since

v4.0.5 R19777 (24. Jul 2017)

Available

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

See Also

frame::remove_url_link
itemlist::remove_url_links

static char* 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)

Since

v4.0.5 R20002 (28. Jul 2017)

Available

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

See Also

document::update_url_links
document::check_url_links

static int 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

Since

v5.0 R35050

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

document::get_articles
get_pdf_accessibility_order

static int 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)

Since

v5.0 R35050

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

document::get_articles
set_pdf_accessibility_order

static int 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)

Since

v4.1 R23010, 9. May 2018

Available

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

See Also

set_placeholder_visibility

static int 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

Since

v4.1 R23010, 9. May 2018

Available

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

See Also

get_placeholder_visibility

static int 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

Preconditions

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

Since

Version 3.0 R1335, 8. May 2009

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

document::notes::import
string
string::alloc

static int 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.

Preconditions

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

Remove all notes from a document. (use "" as srcPath, not 0 with defualt options). 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;
}

Since

Version 3.0 R1335, 8. Mai 2009
kSuppressExternalUpdate seit v3.3 R2812, 5. March 2012

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

document::notes::export_
document::pdf_export
PDF comments

static int 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)

Since

Version 3.0 R1335, 8. May 2009

Available

priint:comet InDesign^® Plug-Ins

See Also

document::notes::import
document::notes::export_
document::notes::hide

static int 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)

Since

Version 3.0 R1335, 8. May 2009

Available

priint:comet InDesign^® Plug-Ins

See Also

document::notes::import
document::notes::export_
document::notes::show

static int 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.

Since

v3.3 R2792, 8. Feb. 2012

Available

priint:comet InDesign^® Plug-Ins, comet_pdf (since R23234, 7. Jun 2018)

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

Since

v3.3 R2792, 8. Feb. 2012

Available

priint:comet InDesign^® Plug-Ins, comet_pdf (since R23234, 7. Jun 2018)

See Also

frame::get_printable
frame::set_printable

static int 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

Since

v4.1, R23456, 14. Jul 2018

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

document::pdf_export
PDF-Export und -Import von Comet-Notizen

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

Since

v3.3 R3827, 6. June 2013

Available

priint:comet InDesign^® Plug-Ins

See Also

notes::delete_groupnotes

static int 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

Since

v3.3 R3827, 6. June 2013

Available

priint:comet InDesign^® Plug-Ins

See Also

notes::change_group

static List 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

Since

v4.1.6 R25450

Available

priint:comet InDesign^® Plug-Ins

See Also

document::notes::show_note et al.
itemlist::doc_notes et al.
frame::note::get_dest et al.

static int 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

Since

v4.1.6 R25450

Available

priint:comet InDesign^® Plug-Ins

See Also

document::notes::find
itemlist::doc_notes et al.
frame::note::get_dest et al.

static int 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

Since

v4.1.6 R25450

Available

priint:comet InDesign^® Plug-Ins

See Also

document::notes::find
itemlist::doc_notes et al.
frame::note::get_dest et al.

static int 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

Since

v4.1.6 R25450

Available

priint:comet InDesign^® Plug-Ins

See Also

document::notes::find
itemlist::doc_notes et al.
frame::note::get_dest et al.

static int 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

Since

v4.1.6 R26001, 30. Sep 2019

Available

priint:comet InDesign^® Plug-Ins

static int 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:

• Both documents must exist and have a valid file path. New unsaved documents cannot be synchronized.
• Both documents must have the same document ID in the XML root element documentID.
• The variant must have the value variant in the XML root element priint_syncDocType.
• The master document must have the value master in the XML root element priint_syncDocType.

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

Since

v4.1.6 R26001, 30. Sep 2019

Available

priint:comet InDesign^® Plug-Ins

See Also

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

Since

v4.1.6 R26001, 30. Sep 2019

Available

priint:comet InDesign^® Plug-Ins

See Also

document::sync::create_variant, document::sync::possible, document::sync::after

static int 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

Since

v4.1.6 R26001, 30. Sep 2019

Available

priint:comet InDesign^® Plug-Ins

See Also

document::sync::create_variant, document::sync::possible, document::sync::before

static int 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

Since

v4.1.6 R26001, 30. Sep 2019

Available

priint:comet InDesign^® Plug-Ins

See Also

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

Since

v4.1.6 R26001, 30. Sep 2019

Available

priint:comet InDesign^® Plug-Ins

See Also

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 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:

• Character styles
• Paragraph styles
• Cell styles
• Table styles
• Table Of Content styles
• Stroke styles
• Object styles

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

Since

v4.1.6 R26001, 30. Sep 2019

Available

priint:comet InDesign^® Plug-Ins

See Also

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

Since

v4.1.6 R26001, 30. Sep 2019

Available

priint:comet InDesign^® Plug-Ins

See Also

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

Since

v4.1.6 R26001, 30. Sep 2019

Available

priint:comet InDesign^® Plug-Ins

See Also

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

Since

v4.1.6 R26001, 30. Sep 2019

Available

priint:comet InDesign^® Plug-Ins

See Also

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

Since

v4.1.6 R26001, 30. Sep 2019

Available

priint:comet InDesign^® Plug-Ins

See Also

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

Since

v4.1.6 R26001, 30. Sep 2019

Available

priint:comet InDesign^® Plug-Ins

See Also

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

Since

v4.1.6 R26263, 11. Nov 2019

Available

priint:comet InDesign^® Plug-Ins

static int 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 "").

Since

v4.2 R32680, 4. Apr 2023

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

comet.CDocument.setMetaData

static char* 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)

Since

v4.2 R32680, 4. Apr 2023

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

comet.CDocument.getMetaData

static int 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 "").

Since

v4.2 R32680, 4. Apr 2023

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

comet.CDocument.setMetaData

static char* 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)

Since

v4.2 R32680, 4. Apr 2023

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

comet.CDocument.getMetaData

static int 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 "").

Since

v4.2 R32680, 4. Apr 2023

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

comet.CDocument.setMetaData

static char* 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)

Since

v4.2 R32680, 4. Apr 2023

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

comet.CDocument.getMetaData

static int 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 "").

Since

v4.2 R32680, 4. Apr 2023

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

comet.CDocument.setMetaData

static char* 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)

Since

v4.2 R32680, 4. Apr 2023

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

comet.CDocument.getMetaData

static int 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 "").

Since

v4.2 R32680, 4. Apr 2023

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

comet.CDocument.setMetaData

static char* 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)

Since

v4.2 R32680, 4. Apr 2023

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

comet.CDocument.getMetaData

static int 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 "").

Since

v4.2 R32680, 4. Apr 2023

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

comet.CDocument.setMetaData

static char* 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)

Since

v4.2 R32680, 4. Apr 2023

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

comet.CDocument.getMetaData

static int 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 "").

Since

v4.2 R32680, 4. Apr 2023

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

comet.CDocument.setMetaData

static char* 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)

Since

v4.2 R32680, 4. Apr 2023

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

comet.CDocument.getMetaData

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

Since

v4.2 R32777, 26. Apr 2023

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

comet.CDocument.setMetaData

static char* 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;
}

Since

v4.2 R32777, 26. Apr 2023

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

comet.CDocument.getMetaData

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

Since

v4.2 R32777, 26. Apr 2023

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

comet.CDocument.setMetaData

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

Since

v4.2 R32777, 26. Apr 2023

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

comet.CDocument.getMetaData

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

Since

v4.2 R32777, 26. Apr 2023

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

comet.CDocument.setMetaData

static ItemList 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)

Since

v5.0, R35050

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

document::articles::count
document::articles::get_nth

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

Since

v5.0, R35050

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

itemlist::articles
document::articles::get_nth

static int 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

Since

v5.0, R35050

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

document::articles::count
itemlist::articles

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

Since

v5.0, R35050

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

document::articles::count
itemlist::articles

static int 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

Since

v5.0, R35050

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

document::articles::count
itemlist::articles

static int 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

Since

v5.0, R35050

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

document::articles::count
itemlist::articles

static int 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

Since

v5.0, R35050

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

document::articles::count
itemlist::articles

static int 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

Since

v5.0, R35050

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

document::article::set_pos
document::articles::count
itemlist::articles

static char* 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

Since

v5.0, R35050

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

document::article::set_name
document::articles::count
itemlist::articles

static int 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

Since

v5.0, R35050

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

document::article::get_name
document::articles::count
itemlist::articles

static int 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

Since

v5.0, R35050

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

document::article::set_use_for_export
document::articles::count
itemlist::articles

static int 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

Since

v5.0, R35050

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

document::article::get_use_for_export
document::articles::count
itemlist::articles

static ItemList 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

Since

v5.0, R35050

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

document::articles::count
itemlist::articles

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

Since

v5.0, R35050

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

itemlist::articles
document::article::get_members

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

Since

v5.0, R35050

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

itemlist::articles
document::article::get_members

static int 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

Since

v5.0, R35050

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

itemlist::articles
document::article::get_members

static int 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

Since

v5.0, R35050

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

document::article::get_members
document::article::members::set_pos
itemlist::articles

static int 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

Since

v5.0, R35050

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

itemlist::articles
document::article::get_members