The class provides methods to ensure the internal representation of InDesign® objects.

Last Change :
24.04.2025, 13:54 Uhr

The class provides methods to ensure the internal representation of InDesign® objects.

static ItemList itemlist::alloc()

Create a new empty list. The list must be deleted again with itemlist::release.

Version 1.2 (21 July 2005)

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

static ItemList itemlist::allframes(
  int add_subframes = 0,
  int tagged_only = 0,
  char* layerName = "",
  int groupID = 0L,
  int includePasteboard = 0)

Create a list of all frames of the document. The list must be deleted again with itemlist::release.

Name Type Default Description
Return ItemList   List of all frames of the documents must be deleted again using itemlist::release!
add_subframes int 0 Sub-frames also in list
tagged_only int 0 Only frames with valid placeholders.

0 means that frames without placeholders will also be added to the list.
layerName String or char* "" Frames must be on the given layer. If the layer does not exist or the specification is empty, the frames can be on any layer.

"" : all layers
"--visible--" : visible layers only
"--active--" : active layer only
otherwise : valid layer name
groupID int 0 Find only frames matching the given group id
0 : ignore group id
includePasteboard int 0 Also include frames on paste board to the result list?

0 : No. Do only return page frames
otherwise : yes
#include "internal/text.h" 
ItemList * frames =
 		itemlist::allframes (
 			[add_subframes
 			[, only_tagged]);

A placeholder script inserts a floating frame taking from several frames into the document and connects this to the start of the text. Morever a series of templates will be loaded, which each contain a list of the create items. These items are collected in the list frames, grouped and then connected as floating frames with the start of the text of the placeholders. 

#include "internal/text.h"

int main ()
{
    DataPool	pool		= datapool::alloc ();
    ItemList	frames		= itemlist::alloc ();
    ItemRef		groupRef	= item::alloc ();
    ItemList	items		= 0;
    float		l			= 0.0;
    float		t			= 0.0;
    float		r, b;
    int			i;
    int			textpos;

    if (!textmodel::available ()) return 0;

    // Insert own frames into the document
    // The templates 2-4 must be set up!
    for (i = 2; i<5; i++)
    {
        // Insert templates
        // Items are thereby automatically allocated
        items = document::place_items (pool, "data", "pageitems", i, l, t);

        // Collect inserted frames
        itemlist::appendlist (frames, items);

        // Next template position
        // Then the list items are deleted. 
        itemlist::bbox (items, &l, &t, &r, &b);
        itemlist::release (items);
        items = 0;
        t = b + 2.0;
    }

    // Group inserted templates
    frame::group (frames, groupRef);

    // Allow group to float
    textmodel::floating (groupRef, textmodel::start (),
     	kRightHanded, 5.0,
     	kBelowTop, 0.0);

    return 0;
}

layerName since Version 1.2.2 (26 Sept. 2005) "--visible--" und "--active--" set Version 1.4 R310, 8. Feb. 2007
groupID since Version 1.4 R334 (13. April 2007)
includePasteboard since v3.3 R5220 (3. Mar 2014)

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

itemlist::selected
itemlist::subframes
itemlist::subframes_of_list
comet.CDocument.getFrames
comet.CLayer.getFrames
comet.CLayer.getItems

static ItemList itemlist::allframes_of_doc(
  ItemRef docRef,
  int add_subframes = 0,
  int tagged_only = 0,
  char* layerName = "",
  int groupID = 0L,
  int includePasteboard = 0)

Create a list of all frames of a document. The function is identical to itemlist::allframes except that the additional first parameter can contain a reference to the document. The list must be deleted again with itemlist::release.

Name Type Default Description
Return ItemList   List of all frames of the documents must be deleted again using itemlist::release!
docRef ItemRef 0 Document to take the frames from
0 : current front document
add_subframes int 0 Sub-frames also in list
tagged_only int 0 Only frames with valid placeholders. 0 means that frames without placeholders will also be added to the list.
layerName String or char* "" Only select frames on this layer. If the layer does not exist or the specification is empty, the frames can be on any layer. "" : all layers
"--visible--" : visible layers only
"--active--" : active layer only
otherwise : valid layer name
groupID int 0 Find only frames matching the given group id
0 : ignore group id
includePasteboard int 0 Also include frames on paste board to the result list?

0 : No. Do only return page frames
otherwise : yes

v3.3 R2851, 12.04.2012
includePasteboard since v3.3 R5220 (3. Mar 2014)

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

allframes
comet.CDocument.getFrames

static ItemList itemlist::pageframes(
  int pageNum,
  int add_subframes = 0,
  int tagged_only = 0,
  char* layerName = "",
  int groupID = 0L,
  char* frameName = 0,
  int includePasteboard = 0)

Create a list of all frames of a document page. The list must be deleted again with itemlist::release.

Name Type Default Description
Return ItemList   List of all frames of a document page, must be deleted again using itemlist::release!
pageNum int - page number (1-based)
-1 : current page

Using InDesign® Server or comet_pdf the current front page is undefined!
add_subframes int 0 Sub-frames also in list
tagged_only int 0 Only frames with valid placeholders. 0 means that frames without placeholders will also be added to the list.
layerName String or char* "" Only select this frames on this layer. If the layer does not exist or the specification is empty, the frames can be on any layer. "" : all layers
"--visible--" : visible layers only
"--active--" : active layer only
otherwise : valid layer name
groupID int 0 Find only frames matching the given group id
0 : ignore group id
frameName String or char* 0 (since CS5 and Comet 3.2) Name of frames. You may use regular expressions here if you want. As an abbraviation of [^\\0]* you can use a simple % sign. Default names are not translated.

0 or "" : ignore names
includePasteboard int 0 (Comet 3.2) Include frames on paste board or not. 0 : not not include
1 : include

Get some frame lists and write them to the log. 

int wpageframes (int pg, int addSub, int hasPlaceholder, char * layer, int groupid, char * name, int includePB)
{
    ItemList		fl	= itemlist::pageframes (pg, addSub, hasPlaceholder, layer, groupid, name, includePB);
    int				i;
    ItemRef			fr	= item::alloc ();

    wlog ("", "# %d frames found on page %d, layer '%s'\n", itemlist::length (fl), pg, layer);
    wlog ("", "#	Subframes	: %d\n", addSub);
    wlog ("", "#	Tagged	: %d\n", hasPlaceholder);
    wlog ("", "#	Cometgroup	: %d\n", groupid);
    wlog ("", "#	Frame name	: '%s'\n", name);
    wlog ("", "#	Include PB	: %d\n\n", includePB);

    for (i=0; i< itemlist::length (fl); i++)
    {
        itemlist::get (fl, fr, i);
        wlog ("", "#	%d (%s)\n", item::getint (fr), frame::get_name (fr));
    }

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

    return 0;
}

int main ()
{
    wpageframes (1, 0, 0, "", 0, "", 0);
    wpageframes (1, 0, 0, "", 0, "", 1);
    wpageframes (1, 0, 0, "Ebene 2", 0, "", 0);
    wpageframes (1, 0, 0, "", 0, "%Cometgroup%", 0);

    return 0;
}

v1.4 R320 (27. Feb. 2007)
groupID since Version 1.4 R334 (13. April 2007)
frameName and includePasteboard since CS5 and Version 3.2 R2223, 14. Dec. 2010

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CPage.getFrames

static ItemList itemlist::pageframes_of_doc(
  ItemRef docRef,
  int pageNum,
  int add_subframes = 0,
  int tagged_only = 0,
  char* layerName = "",
  int groupID = 0L,
  char* frameName = 0,
  int includePasteboard = 0)

Create a list of all frames of a document page. The frame is identically to itemlist::pageframes that the additional first parameter must contain a reference to the document. The list must be deleted again with itemlist::release.

Name Type Default Description
Return ItemList   List of all frames of a document page, must be deleted again using itemlist::release!
docRef ItemRef - document reference
0 : current front document
pageNum int - page number (1-based)
-1 : (only if docRef != 0) current page

Using InDesign® Server or comet_pdf the current front page is undefined!
add_subframes int 0 Sub-frames also in list
tagged_only int 0 Only frames with valid placeholders. 0 means that frames without placeholders will also be added to the list.
layerName String or char* "" Only select frames on this layer. If the layer does not exist or the specification is empty, the frames can be on any layer. "" : all layers
"--visible--" : visible layers only
"--active--" : active layer only
otherwise : valid layer name
groupID int 0 Find only frames matching the given group id
0 : ignore group id
frameName String or char* 0 (since CS5 and Comet 3.2) Name of frames. You may use regular expressions here if you want. As an abbraviation of [^\\0]* you can use a simple % sign. Default names are not translated.

0 or "" : ignore names
includePasteboard int 0 (Comet 3.2) Include frames on paste board or not. 0 : not not include
1 : include

Copy the frames of page 3 of a document to the current front page. 

int main ()
{
    ItemRef		d1		= document::alloc ("$DESKTOP/base.indd");
    ItemList	src		= itemlist::pageframes_of_doc (d1, 3);
    ItemList	added	= itemlist::alloc ();

    itemlist::duplicate (0, src, 10.0, 20.0);

    return 0;
}

v3.3 R2851, 12.04.2012

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CPage.getFrames

static ItemList itemlist::chained(
  ItemRef frameRef = 0,
  int add_subframes = 0,
  int tagged_only = 0,
  char* layerName = "",
  int groupID = 0L)

Create a list of all linked frames of a text. The list must be deleted again with itemlist::release.

Name Type Default Description
Return ItemList   List of linked frames of a text, must be deleted again using itemlist::release!
frameRef ItemRef - valid frame ref
0 : current textframe
add_subframes int 0 Sub-frames also in list
tagged_only int 0 Only frames with valid placeholders. 0 means that frames without placeholders will also be added to the list.
layerName String or char* "" Only select frames on this layer. If the layer does not exist or the specification is empty, the frames can be on any layer. "" : all layers
"--visible--" : visible layers only
"--active--" : active layer only
otherwise : valid layer name
groupID int 0 Find only frames matching the given group id
0 : ignore group id

v1.4 R335 (16. Apr. 2007)

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

comet.CFrame.getChain

static ItemList itemlist::intersections(
  ItemRef frameRef = 0,
  int add_subframes = 0,
  int tagged_only = 0,
  char* layerName = "",
  int groupID = 0L)

Create a list of all frames interseting the given frame. If the given item reference is a group, this object is handled as one object. All other grouped frames are handled as single objects. The list may contain groups and part of groupes as well as single frames. You may not remove, move or group this objects in a whole..

The list is sorted by the Z order of the objects.

The list must be deleted again with itemlist::release.

Name Type Default Description
Return ItemList   List of all frames intersecting the given one.
frameRef ItemRef 0 Valid frame
0 : current script frame

Version 3.1 R1723, 3. Feb. 2010

priint:comet InDesign® Plug-Ins, comet_pdf

static ItemList itemlist::masteritems(
  ItemRef docRef,
  char* mastername,
  int pageindex,
  int linkedOnly = 0,
  int placeholderID = 0,
  int id1 = 0,
  int id2 = 0,
  int id3 = 0,
  char* sid = 0,
  char* info1 = 0,
  char* info2 = 0)

Create a list of all items on a parent page. The list must be deleted again with itemlist::release.

Name Type Default Description
Return ItemList   List of all frames and subframes of a parent page
docRef ItemRef - Valid document reference 0 : Current (script) document
mastername String or char* - Master page name. If empty, pageIndex is used as normal 1-based page index
pageindex int - 1-based page index

mastername not empty : Index in parent spread. On facing pages :
    1 : left parent page
    2 : right parent page

mastername 0 or "" : normal page index. The parent page of this page is used in this case. On facing pages with a right page as first page
    1 : right parent page
    2 : left parent page
linkedOnly int 0 Only collect placeholdered frames?
0 : All frames
1 : Only frames with placeholder
placeholderID int 0 Only collect frames with this placeholder.
0: Ignore parameter.
id.., sid int, String or char* 0 Frame must be linked with the given object. Ignored if all values are 0.
info1, info2 String or char* 0 Info1 and Info2 of the frame placeholder. If the entry is empty, it is not checked. A frame is included in the list if its placeholder has info1 or info2.

Get the frames of the right parent page of parent spread 'A-Parent'. 

int main ()
{
    ItemList		masters	= itemlist::masteritems (0, "A-Parent", 2, 0);
    ItemRef			f		= item::alloc ();
    int				i;

    wlog ("", "ParentPageitems  : %d\n", itemlist::length (masters));

    for (i = 0; i < itemlist::length (masters); i++)
    {
        itemlist::get (masters, f, i);

        placeholder::link (f, 3, 100, 10, 0, -1, -1, "");
        placeholder::load (f, 3, -1, -1, 1);

    }

    return 0;
}

Like example 1 but using the nice itemlist::apply: 

int main ()
{
    ItemList			masters	= itemlist::masteritems (0, "A-Parent", 2, 0);

    itemlist::apply (placeholder::link, masters, 1, 0, 3, 100, 10, 0, -1, -1, "");
    itemlist::apply (placeholder::load, masters, 1, 0, 3, -1, -1, 1);

    return 0;
}

If you do not know the parent spreads name, use the page index. 

int main ()
{
    ItemList			masters	= itemlist::masteritems (0, "", 3, 0);

    itemlist::apply (placeholder::link, masters, 1, 0, 3, 100, 10, 0, -1, -1, "");
    itemlist::apply (placeholder::load, masters, 1, 0, 3, -1, -1, 1);

    return 0;
}

Version 2.1, R1760, 20.02.2010

priint:comet InDesign® Plug-Ins, comet_pdf

To work with (overridden) parent page items use the following functions : frame::is_masteritem_overriden, frame::is_overriden_masteritem
frame::override_masteritem und frame::remove_masteritem_override.
comet.CDocument.getMasterPageItems

static ItemList itemlist::selected(
  int add_subframes = 0,
  int tagged_only = 0,
  char* layerName = "",
  int groupID = 0L)

Create a list of all selected frames of the document. The list must be deleted again with itemlist::release.

Using comet_pdf the function is a NOP only and returns 0 always.

Name Type Default Description
Return ItemList   List of all selected frames of the documents must again be deleted with itemlist::release!
add_subframes int 0 Sub-frames also in the list
tagged_only int 0 Only frames with valid placeholders. 0 means that the frame without placeholder will also be added to the list.
layerName String or char* "" Only select frames on this layer. If this layer does not exist or the specification, the frame can be on any layer.
groupID int 0 Find only frames matching the given group id
0 : ignore group id 
ItemList frames =
 		itemlist::allframes (
 			[add_subframes
 			[, only_tagged]);

layerName since Version 1.2.2 (26 Sept. 2005)
groupID since Version 1.4 R334 (13. April 2007)

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

itemlist::allframes
itemlist::subframes
itemlist::subframes_of_list
comet.frame.getSelected

static ItemList itemlist::inlines(
  ItemRef frameRef = 0,
  int pos = 0,
  int len = -3)

Get all inlines and anchored frames of a text or text range.

Use textmodel::inlinepos, frame::get_anchor and textmodel::get_table to get more infos about the frames.

Use kTotalEnd instead of kEnd to retreive the inlines of table cells too.

Be carefull using inlines. Do not delete inlines directly. Remove the text containing te anchor instead or make the frame a normal page frame be using frame::release_inline first.

Name Type Default Description
Return ItemList   List of all inlines and anchored frame of the given text or text range
frameRef ItemRef 0 Valid text frame reference (gFrame)

0 : current script frame
pos int 0 start of text range
len int kTotalEnd length of text range

kTotalEnd : whole text including all tables
kEnd : whole text
#include "internal/text.h"
#include "internal/types.h"
#include "internal/text.h"

int main ()
{
    ItemList	li	= itemlist::inlines (gFrame, 0, kTotalEnd);
    ItemRef		fr	= item::alloc ();
    int			i;

    if (li)
    {
        wlog ("", "Frame %d contains %d inlines\n", item::getint (gFrame), itemlist::length (li));
        for (i=0; i< itemlist::length (li); i++)
        {
            fr	= itemlist::get (li, fr, i);
            wlog ("", "	%d : %d @ textpos %d\n", i+1, item::getint (fr), frame::inlinepos (fr));

            frame::color_rgb (fr, 255, 128, 0);
        }
    }

    return 0;
}

Get all inlines of the currently selected table cell. 

ItemList inlines_of_cell (ItemRef frame, Table T, int row, int col)
{
    ItemList	inlines		= itemlist::inlines (frame);
    ItemList	cellframes	= itemlist::alloc ();
    ItemRef		f			= item::alloc ();
    int			start, len, pos, i;

    table::cell::get_textpos (T, col, row, &start, &len);

    for (i = 0; i < itemlist::length (inlines); i++)
    {
        itemlist::get (inlines, f, i);
        pos = frame::inlinepos (f);
        if (pos >= start)
        {
            itemlist::append (cellframes, f);
        }
    }

    itemlist::release (inlines);
    return cellframes;
}

int main ()
{
    int 		start, end, row, col;
    Table		T 		= table::alloc ();
    ItemRef		frame	= item::alloc ();
    ItemList	inlines;

    textmodel::selection (&start, &end, frame, 0, T, &col, &row);
    if (table::is_valid (T))
    {
        inlines			= inlines_of_cell (frame, T, row, col);

        wlog ("", "# %d inlines in cell [r%d, c%d]\n", itemlist::length (inlines), row, col);

        itemlist::release (inlines);
    }

    return 0;
}

Version 2.1 R2200, 28. 10. 2010

priint:comet InDesign® Plug-Ins, comet_pdf

textmodel::inlinepos
frame::get_anchor
textmodel::get_table
comet.CTextModel.getInlines

static ItemList itemlist::hyperlinks(ItemRef frameRef = 0)

Get a list of all hyperlinks of the text of a frame. If the frame is part of a text chain, all hyperlinks of the text chain are found. The results are sorted by text positions.

Name Type Default Description
Return ItemList   List of all hyperlinks of the text of the given frame, must be deleted again with itemlist::release!
frameRef ItemRef 0 Reference to a text frame

0 : current script frame

Visit all hyperlinks of a frame in the order of their text position. 

int by_list (ItemRef fr)
{
    ItemList 	hys	= itemlist::hyperlinks (fr);
    ItemRef		hy	= item::alloc ();
    int			i, start, len;

    for (i = 0; i < itemlist::length (hys); i++)
    {
        itemlist::get (hys, hy, i);

        start = hyperlink::get_pos (hy, &len);
        printf ("YYYYY %d : %d %d\n", i+1, start, len);
    }

    return 0;
}

v4.1.8 R29140, 21. Sep 2021

priint:comet InDesign® Plug-Ins, comet_pdf

hyperlink::get_pos
hyperlink::count
hyperlink::get_nth

static ItemList itemlist::articles(ItemRef docRef = 0)

Get a list of all articles in a document. The function is equivalent to the document::get_articles function.

The articles in a document can also be edited manually using the Articles panel.

Name Type Default Description
Return ItemList   List of all articles in the document

The results list must be deleted again with itemlist::release!

docRef ItemRef - Document specification

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

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

v5.0, R35050

priint:comet InDesign® Plug-Ins, comet_pdf
document::articles::count
document::articles::get_nth

static ItemList itemlist::doc_notes(ItemRef docRef = 0)

Create a list of all Comet Notes of a document.

Only visible Comet Notes are considered by InDesign® and the list contains the frames of the notes. To make all Comet Notes of a document visible, use the document::notes::show function.

In comet_pdf the list contains references to the notes themselves. The elements of the list are not frames and may only be used in notes functions!

To find notes about your content, use the document::notes::find function.

Name Type Default Description
Return ItemList   List of all Comet Notes of the given document. Only visible notes are taken into account by InDesign®!

The list must be deleted again with itemlist::release!
docRef ItemRef 0 Document Reference

0 : Current document of the script

Get all Comet Notes of a document. 

#include "internal/types.h"

int main ()
{
    ItemRef 		fr		= item::alloc ();
    int           	i, tyte, dest, result;
    ItemList 		notes;

    if (gRun > 1)	return 0;

    notes = itemlist::doc_notes ();
    itemlist::select (notes);

    for (i = 0; i < itemlist::length (notes); i++)
    {
        itemlist::get (notes, fr, i);
        frame::note::get_dest (fr, &type, &dest);
        wlog ("", "Note	%d : Type = %d, Dest = %d\n", item::getint (fr), type, dest);
    }

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

    return 0;
}

v4.2 R32080, 2. Jan 2023

priint:comet InDesign® Plug-Ins, comet_pdf

page_notes
group_notes
frame_notes
frame::note::get_dest
frame::note::change_dest
document::notes::show
document::notes::find

static ItemList itemlist::page_notes(
  ItemRef docRef,
  int dest,
  int type)

Create a list of all Comet Notes of a given page or page number.

Only visible Comet Notes are considered by InDesign® and the list contains the frames of the notes. To make all Comet Notes of a document visible, use the document::notes::show function.

In comet_pdf the list contains references to the notes themselves. The elements of the list are not frames and may only be used in notes functions!

To find notes about your content, use the document::notes::find function.

Name Type Default Description
Return ItemList   List of all Comet Notes of the given page. Only visible notes are taken into account by InDesign®!

The list must be deleted again with itemlist::release!
docRef ItemRef - Document Reference

0 : Current script document
pg int - 1-based page number or UID of the page.
type int - Type of requested notes

kNoteTypePage : Page note. Page notes move with the respective page. The expected input for pg is the UID of the desired page. You can get the UID of a page using the function page::get_uid

kNoteTypePageIndex : Page index note. The note is placed on same page number always. The input for pg is expected to be the 1-based page index.
#include "internal/types.h"

Get all Comet Notes fixed on page 2 of the script document. 

#include "internal/types.h"

int main ()
{
    ItemRef 		fr		= item::alloc ();
    int           	i, tyte, dest, result;
    ItemList 		notes;

    if (gRun > 1)	return 0;

    notes = itemlist::page_notes (0, 2, kNoteTypePageIndex);
    itemlist::select (notes);

    for (i = 0; i < itemlist::length (notes); i++)
    {
        itemlist::get (notes, fr, i);
        frame::note::get_dest (fr, &type, &dest);
        wlog ("", "Note	%d : Type = %d, Dest = %d\n", item::getint (fr), type, dest);
    }

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

    return 0;
}

v4.2 R32080, 2. Jan 2023

priint:comet InDesign® Plug-Ins, comet_pdf

doc_notes
group_notes
frame_notes
frame::note::get_dest
frame::note::change_dest
document::notes::show
document::notes::find

static ItemList itemlist::group_notes(ItemRef frameRef = 0)

Create a list of all Comet Notes of the Comet Group of a frame. The notes are of type kNoteTypeGroup.

Only visible Comet Notes are considered by InDesign® and the list contains the frames of the notes. To make all Comet Notes of a document visible, use the document::notes::show function.

In comet_pdf the list contains references to the notes themselves. The elements of the list are not frames and may only be used in notes functions!

To find notes about your content, use the document::notes::find function.

Name Type Default Description
Return ItemList   List of all Comet Notes of the Comet Group of the given frame. Only visible notes are taken into account by InDesign®!

The list must be deleted again with itemlist::release!
frameRef ItemRef 0 arbitrary frame of a Comet Group (not the integer ID of the group!)

0 : Comet Group of the current script frame
#include "internal/types.h"

Get all Comet Notes of Comet Group of the current script frame. 

#include "internal/types.h"

int main ()
{
    ItemRef 		fr		= item::alloc ();
    int           	i, tyte, dest, result;
    ItemList 		notes;

    if (gRun > 1)	return 0;

    notes = itemlist::group_notes ();
    itemlist::select (notes);

    for (i = 0; i < itemlist::length (notes); i++)
    {
        itemlist::get (notes, fr, i);
        frame::note::get_dest (fr, &type, &dest);
        wlog ("", "Note	%d : Type = %d, Dest = %d\n", item::getint (fr), type, dest);
    }

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

    return 0;
}

v4.2 R32080, 2. Jan 2023

priint:comet InDesign® Plug-Ins, comet_pdf

doc_notes
page_notes
frame_notes
frame::note::get_dest
frame::note::change_dest
document::notes::show
document::notes::find

static ItemList itemlist::frame_notes(ItemRef frameRef = 0)

Create a list of all Comet Notes of a given frame. The notes are of type kNoteTypeFrame.

Only visible Comet Notes are considered by InDesign® and the list contains the frames of the notes. To make all Comet Notes of a document visible, use the document::notes::show function.

In comet_pdf the list contains references to the notes themselves. The elements of the list are not frames and may only be used in notes functions!

To find notes about your content, use the document::notes::find function.

Name Type Default Description
Return ItemList   List of all Comet Notes of the given frame. Only visible notes are taken into account by InDesign®!

The list must be deleted again with itemlist::release!
frameRef ItemRef 0 Valif frame reference

0 : Current script frame
#include "internal/types.h"

Get all Comet Notes of Comet Group of the current script frame. 

#include "internal/types.h"

int main ()
{
    ItemRef 		fr		= item::alloc ();
    int           	i, tyte, dest, result;
    ItemList 		notes;

    if (gRun > 1)	return 0;

    notes = itemlist::frame_notes ();
    itemlist::select (notes);

    for (i = 0; i < itemlist::length (notes); i++)
    {
        itemlist::get (notes, fr, i);
        frame::note::get_dest (fr, &type, &dest);
        wlog ("", "Note	%d : Type = %d, Dest = %d\n", item::getint (fr), type, dest);
    }

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

    return 0;
}

v4.2 R32080, 2. Jan 2023

priint:comet InDesign® Plug-Ins, comet_pdf

doc_notes
page_notes
group_notes
frame::note::get_dest
frame::note::change_dest
document::notes::show
document::notes::find

static ItemList itemlist::subframes(
  ItemRef parent,
  int tagged_only = 0,
  char* layerName = "",
  int groupID = 0L)

Create a list of sub-frames of an InDesign® group frame. The list must be deleted again with itemlist::release. In order to ascertain the sub-frames of a total list use the function itemlist::subframes_of_list.

Name Type Default Description
Return ItemList   List of all sub-frames of a frame must be deleted again with itemlist::release!
parent ItemRef - Reference to a frame
tagged_only int 0 Only frame with valid placeholder 0 means that the frame without placeholder will also be added to the list.
layerName String or char* "" Only select frames on this layer. If this layer does not exist or the specification, the frame can be located on a user-defined layer.
groupID int 0 Find only frames matching the given group id
0 : ignore group id 
ItemList frames =
 		intelist::subframes (
 			parent
 			[, tagged_only]);

layerName since Version 1.2.2 (26 Sept. 2005)
groupID since Version 1.4 R334 (13. April 2007)

priint:comet InDesign® Plug-Ins, comet_pdf

itemlist::subframes_of_list

static ItemList itemlist::subframes_of_list(
  ItemRef parents,
  int tagged_only = 0,
  char* layerName = "",
  int groupID = 0L)

Create a list of sub-frames of a frame list. Subframes are collected recursively and the result will not contain any group frame. The frames of span[src]{parents} are not contained in the result. The list must be deleted again with itemlist::release.

Name Type Default Description
Return ItemList   List of all sub-frames of a frame. Must be deleted again with itemlist::release!
parents ItemList - Valid ItemList of frames
tagged_only int 0 Only frame with valid placeholder 0 means that the frame without placeholder will also be added to the list.
layerName String or char* "" Only select frames on this layer. If this layer does not exist or the specification, the frame can be on any layer.
groupID int 0 Find only frames matching the given group id
0 : ignore group id 
ItemList frames =
 		intelist::subframes (
 			parent
 			[, tagged_only]);

layerName since Version 1.2.2 (26 Sept. 2005)
groupID since Version 1.4 R334 (13. April 2007)

priint:comet InDesign® Plug-Ins, comet_pdf

itemlist::subframes_of_list

static int itemlist::bbox(
  ItemList frames,
  float* left,
  float* top,
  float* right,
  float* bottom,
  int spreadRelative = 0,
  int lastPage = 0,
  int spreadWide = 0)

Ascertain the frame surrounding the frame of the list. The specification are given in points.

Bounding boxes are only determined page- or spread-wide! If the frame list contains entries of different pages or spreads, only the frames of the first/last page or spread are used to determine the bounding box.

Name Type Default Description
Return int   0 or ErrorCode
frame ItemList - Frame list
left float* - X position of the frame which is located at the furthest point left of all frames in the list.
top float* - Y position of the frame which is located at the furthest position above all the frames in the list.
right float* - X position of the right side of the frame which is located at the furthest position left of all the frames in the list.
bottom float* - Y position of the bottom side of the frame which is located at the furthest position below all the frames in the list.
spreadRelative int 0 Get the coordinates relative to the page or to the spread?

0 : page relative

1 : spread relative
lastPageOrSpread int 0 Use frame of first or last page/spread?

0 : First page/spread
1 : Last page/spread
spreadWide int 0 If the frame list contains frames of different pages, should the frames of the first/last page be used or the frames of the first/last spread?

0 : page only
1 : spread

Parameter spreadRelative since v2.1, R 1750, 9. Feb. 2010
Parameter lastPageOrSpread and Parameter spreadWide since v4.0.5 R13604, 12. Sep 2016

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

static void itemlist::release(ItemList frames)

Release of memory occupied by an ItemList. In order to simply empty the list, use the command itemlist::clear.

Name Type Default Description
frames ItemList - List to be deleted. 
itemlist::release (frames);


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

static ItemRef itemlist::get(
  ItemList frames,
  ItemRef result,
  int index)

Get the i-th element of a specified list. Where the indices are false, a 0 will be returned.

Name Type Default Description
Return ItemRef   Frame reference or 0
frames ItemList - Frame list
frame ItemRef - Reserved memory for the result
i int - Index 
frame = itemlist::get (frames, frame, i);


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

item::alloc
itemlist::count

static int itemlist::length(ItemList frames)

State the length of the list.

Name Type Default Description
Return int   Length of the list
frames ItemList Frame list   
len = itemlist::length (frames);


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

static int itemlist::select(ItemList frames, int addTo = 0)

Select the frame of a list in the document.

Using comet_pdf the function is a NOP only.

Name Type Default Description
Return int   0 or ErrorCode
frames ItemList Frame list  
addTo int 0 Replace or extent selection
0 : Replace
sonst : add to 
err_code = itemlist::select (items);

Parameter addTo since version 1.4 R323, 21. Mar. 2007

priint:comet InDesign® Plug-Ins, comet_pdf

static int itemlist::get_pos(ItemList frames, ItemRef obj)

Ascertain the position of an entry within the list. Position specifications are 0-based. If the entry is empty or could not be found, the function returns -1.

Name Type Default Description
Return int   0-based list position of the object
-1 : Error or not found
frames ItemList - Frame list
obj ItemRef - searched object

1.2.1 (25 August 2005)

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

static int itemlist::append(ItemList frames, ItemRef obj)

Expand the list by one element. The element will be appended to the end of the list.

Name Type Default Description
Return int   0 or ErrorCode
frames ItemList - Frame list
obj ItemRef - new object

1.2.1 (25 August 2005)

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

static int itemlist::appendlist(ItemList frames, ItemList moreframes)

Expand the list with an additional list.

Name Type Default Description
Return int   0 or ErrorCode
frames ItemList - Frame list
moreframes ItemList - List the entries of which are to be added to the existing list.

1.2.1 (25 August 2005)

priint:comet InDesign® Plug-Ins, comet_pdf

static int itemlist::insert(
  ItemList frames,
  ItemRef obj,
  int index)

Expand the list by one element. The element will be inserted in front of the specified position in the list.

Name Type Default Description
Return int   0 or ErrorCode
frames ItemList - Frame list
obj ItemRef - new object
index int - Position in front of which the insert is to be made

1.2.1 (25 August 2005)

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

static int itemlist::remove(ItemList frames, ItemRef obj)

Delete an object from the list (but not the object referenced by the given list entry).

Name Type Default Description
Return int   0 or ErrorCode
frames ItemList - Frame list
obj ItemRef - Object to be deleted

1.2.1 (25 August 2005)

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

static int itemlist::remove_pos(ItemList frames, int index)

Delete an object from the list. The object is identified by means of the 0-based list position.

Name Type Default Description
Return int   0 or ErrorCode
frames ItemList - Frame list
index int - 0-based list position of the object to be deleted

1.2.1 (25 August 2005)

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

static int itemlist::clear(ItemList frames)

Remove all objects from the list. The list remains preserved. In order to delete the list itself from the memory, use the command itemlist::release.

Name Type Default Description
Return int   0 or ErrorCode
frames ItemList - Frame list

1.2.1 (25 August 2005)

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

static int itemlist::set_creationdate(ItemList frames)

Reset the frame date of every frame in the list. For the date, the current time information of the computer will be used.

Name Type Default Description
Return int   0 or ErrorCode
frames ItemList - Frame list

Version 1.2.1 (30 August 2005)

priint:comet InDesign® Plug-Ins, comet_pdf

static int itemlist::apply(
  scriptfunc function,
  ItemList frames,
  int frameIndex,
  ...)

Apply a function to all entries of a list. If an error occurs in relation to a list entry, the processing will be interrupted. For the function every script function can be used. In the parameter frameIndex it is stated which position in the function parameter the list element is to be inserted in each case.

In the following call, the function linklist::load will be applied to all the elements of the list frames. A valid version of linklist::load expects 3 parameters : a link list, a int and a target frame. These values are stated by apply behind the standard parameters. At the third position of the function parameter linklist::load a frame is expected, therefore a 3 is found in front of the ll2. The frame variable (hinter kDesignateUndef) can contain a user-defined value.

itemlist::apply (linklist::load, frames, 3, ll2, kDesignateUndef, 0);

For the function, every script function can be used. To receive no errors with an external script compiler (CodeWarrior, Visual Studio, ...) the corresponding function pointer types must be defined where possible, and the corresponding definition inserted by apply in itemlist.h. For more see the examples.

Applying frame::moveto to a list of frames will move frames relativ to the frames bounding box and the bounding box will get the new position.werden die Rahmen so verschoben, dass das umschließende Rechteck an der neuen Position liegt und die Rahmen der Liste ihre relativen Abstände zueinander behalten.

Name Type Default Description
Return int   0 or ErrorCode. In the event that an error occurs in a list entry, the processing will be interrupted with an error code.
function Script function - Name of a script function which is to be executed for all elements of the following list of the ItemList type.
frames ItemList - List of the frames to be processed
frameIndex int - 1-based index, which states which of the following parameters are to be replaced during processing of the list frames by the current list element in each case.

0 : No parameter is to be replaced
1 : Replace the first following parameter frame index
:
... dependent on function - Parmeter for the call of the function function.
#include "internal/types.h"

Load the placeholder of all frames of a layer. 

#include "internal/types.h"

int main ()
{
    LinkList 	ll2 	= linklist::alloc (0);
    ItemList	frames	= 0;

    frames = itemlist::allframes (0, 0, "fr");

    itemlist::apply (
     	linklist::load, frames, 3,
     	ll2, kDesignateUndef, 0);

    itemlist::release (frames);

    return 0;
}

Move a list of frames to an new position. Distances between frames are untouched. 

itemlist::apply (

 	frame::moveto, frames, 1, 0,

 	leftMargin, topMargin, newPage, 0);

The example describes how the cscript header of an external compiler can be adapted, in order that no errors occur in apply when undertaking the syntax checking of a function application. The function frame::image_scale is to be used in apply. Therefore the following definitions are necessary.

  1. Definition of a function type with the parameter of frame::image_scale. This definition is inserted prior to the definition of the class in itemlist.h.

    typedef int (*image_scale_fn)(ItemRef frameRef, float x, float y);

  2. Definition of a version of apply with this function type. This definition can be inserted after the pre-existing definitions of apply in itemlist.h.

    static int apply (image_scale_fn function, ItemList frames, int frameIndex, ...); 

 


priint:comet InDesign® Plug-Ins, comet_pdf

logical_groups

static int itemlist::apply1(
  scriptfunc function,
  ItemList frames,
  int frameIndex,
  ...)

Apply a function on all entries of a list. After the execution of the function, the specified list frames is deleted. For description see apply.

#include "internal/types.h"

Load the placeholder of all frames of a layer. 

#include "internal/types.h"

int main ()
{
    LinkList 	ll2 	= linklist::alloc (0);

    itemlist::apply1 (
     	linklist::load,
     	itemlist::allframes (0, 0, "fr"),
     	3,
     	ll2, kDesignateUndef, 0);

    return 0;
}


priint:comet InDesign® Plug-Ins, comet_pdf

static ItemListList itemlist::logical_groups(
  ItemList frames,
  int domain,
  char* layerName,
  int preferGroup,
  char* method,
  ...)

Collect a sub-list of frames that satisfy the same logical conditions. For every frame from of a given list all frames with same conditions are collected. To search for equal frames, you can use either the the whole document, the current page or only the given list.

As the result of the function you will get a list of frame lists. Each list contains only logical equal frames. If the given list contains the frames A and B and A ≅ B under the given condition(s), no list is created for frame B. If A not equal B and there exists a third frame C with A ≅ B and A ≅ C, C is inserted in both result lists.

Uncomparable frames are ignored and don't appear in any result list. For instance, to compare all xml attributes of two frames, each of the frames must have at least one xml attribute.

Sub frames are added to the search automatically.

Name Type Default Description
Return ItemListList   List of frame lists. The list is allocated automatically. Use itemlistlist::release to free this list in case of further calls of the function.
frames ItemList - List of frames to check
domain int - Where to look for equal frames?

kSearchDocument
kSearchPage
kSearchFrameList : Only search in list frames
layerName String or char* - Search only given layer

"" : All layers
"--visible--" : visible layers only
"--active-- : active layer only
else : case sensitive layer name
preferGroup int - Put the matching frames itself or their top most parent group to the result lists 0 : frames itself 1 : top most group parent
method String or char* - method to compare frames

"xml", "attr1", ...

Use the frames XML element to compare. A list of attribut names (char*) must follow.
Frames are equal if the attributes exists in both frames and has the same values. With the shortcut "*" all attributes except href are checked.

"script", 123

Use the given script to compare. The frames are given as gMasterFrame and gCheckFrame in the script.

Validation
Before we can compare frames we must be sure that a given frame from frames is valid in respect to the given conditions. The script is called once for every item of the given frame list to check this. In this run, gCheckFrame is equal to 0.

Return values
return 0; : Valid
return 1; : Not valid

Comparison
Now every frame of the list frames is compared with every frame of the given domain (and layerName (if given)). In these calls, gCheckFrame contains valid frames.

Return values
return 0; : Equal
return 1; : B>Not equal
#include "internal/types.h"

Search all frames of the current page and collect their lists of equal frames. Frames are equal, if their XML attributes a and b have the same values. Frames of a group are colored than with the same color. (You may find an example file for InDesign® CS here.) 

int main ()
{
    ItemListList	ill;
    ItemList		ff	= itemlist::pageframes (-1);
    ItemList		lo;

    ill = itemlist::logical_groups (ff, kSearchPage, "", 1, "xml", "a", "b");
    if (!ill)
    {
        showmessage ("No groups found");
        return 0;
    }

    for (lo = itemlistlist::first (ill); lo; lo = itemlistlist::next (ill))
    {
        itemlist::apply (
         	frame::color_rgb, lo, 1,
         	0, random (255), random (255), random (255), -1, -1);
    }

    itemlistlist::release (ill);
    itemlist::release (ff);
    return 0;
}

To compare all attributes of the frames, simply change the call to logical_groups to the following: 

ill = itemlist::logical_groups (ff, kSearchPage, "", 1, "xml", "*");

If the both frames are text frames and the text begins with the same three letters, the frames should be congruent. To check this conditions, you create a new action (here we use 30152) and change the call to logical_groups: 

ill = itemlist::logical_groups (ff, kSearchPage, "", 1, "script", 30152);

// and the script 30152

int main ()
{
    String	s1	= string::alloc ();
    String	s2	= string::alloc ();
    char*	b1	= frame::gettext (gMasterFrame, s1, 0, 3);
    char*	b2	= frame::gettext (gCheckFrame, s2, 0, 3);

    // Validation
    if (!gCheckFrame) return (b1 == 0);

    // Comparison
    if (!b1 || !b2)	return 1;
    return strcmp (string::get (s1), string::get (s2));
}

Version 1.4 R320 (2. March 2007)

priint:comet InDesign® Plug-Ins

itemlistlist
ItemListList
allframes
pageframes
selected

static int itemlist::create_snippet(
  ItemList frames,
  long ID,
  long ID2,
  long ID3,
  char* stringID,
  char* name = "",
  char* description = "",
  long typeID = 0,
  long domainID = 0,
  long stateID = 0,
  long spreadTypeID = 0,
  long leftID = 0,
  long middleID = 0,
  long rightID = 0,
  long snippetScriptID = 0,
  char* typeName = "",
  char* domainName = "",
  char* stateName = "")

Create a new snippet. The function is NOT implemented for InDesign® Server.

Depending on the number of given parameters, the function has two different meanings :

  1. 5 and more parameters : Create a Comet snippet in pageitems.

    With exactly 5 five parameters, the templates meta data dialog is show to set the snippets meta data like name, type, ... . With more than 5 parameters, the meta data are taking from this parameters. Missing values are filled by their defaults (0 resp. "").

    The snippet is saved in the INDD format and is marked as to be a Comet snippet in the attribute pageitems.KindID (value 2).

    Comet snippets must point to a data pool object. The id of this object is written in the attributes
    • pageitems.recordid, pageitems.recordid2, pageitems.recordid2
    • pageitems.recordstringid
    If these attributes are missing, the function will return an error.

  2. Exactly 3 parameters : Create an InDesign® snippet (IDMS).

The variants with five or more parameters need the meta data dialog for templates and can therefore not be used in InDesign® Server. In these cases the function will return the error code -1199 (notDefinedErr).

Name Type Default Description
Return int   ID of the newly created snippet
0 : No snippet created, e.g an error occured

If you create an InDesign® snippet (three parameter call) an Errorcode or 0 is returned.
⇨ Comet snippet
frames ItemList - list of valid document frames (see pageframes)
0 : current document selection
ID int - recordID of snippet
ID2 int - recordID2 of snippet
ID3 int - recordID3 of snippet
stringID String or char* - StringID of snippet
name String or char* "" Name of the new snippet. If missing, the snippet dialog is invoked
description String or char* "" descriction for the snippet
typeID int 0 type ID of new snippet
domainID int 0 domain ID of new snippet
stateID int 0 state ID of new snippet
spreadTypeID int 0 Pagetype for the new snippet 0 : any 1 : left pages 2 : unisex 3 : right pages
leftID int 0 Which snippet to use on left pages, if the snippet is allowed on unisex/right pages only?
middleID int 0 Which snippet to use on unisex pages, if the snippet is allowed on left/right pages only?
rightID int 0 Which snippet to use on right pages, if the snippet is allowed on left/unisex pages only?
snippetScriptID int 0 get the snippet id from a script

The script must be defined in an action of class 15
typeName String or char* "" (XML and SOAP only) Name of snippet type
domainName String or char* "" (XML and SOAP only) Name of snippet domain
stateName String or char* "" (XML and SOAP only) Name of snippet state
⇨ InDesign®-Snippet
frames ItemList - list of valid document frames (see pageframes)
0 : current document selection
fullpath String or char* - Complete path for snippet file. The extension is managed by the function
override int - Override existing file?

0 : no
1 : yes
#include "internal/types.h"

Create an InDesign® snippet and import this file into the current database. 

#include  "internal/types.h"

int main ()
{
    Query 		qu 		= sql::query (sql::dbconnection ());
    long		id		= 0;
    char		path	[2000];
    ItemList	frames	= itemlist::selected ();
    Image		img		= 0;
    float		l, t, r, b;

    // create content
    strcpy (path, "$DESKTOP/aaa");
    itemlist::create_snippet (frames, path, 1);
    itemlist::bbox (frames, &l, &t, &r, &b);
    img = image::snapshot_frames (frames, 100);

    // next free pageitems id
    query::send (qu, "select max(id) from pageitems");
    query::output (qu, kInt, &id);
    query::exec (qu);
    while (query::fetch (qu)) {}
    id = id + 1;

    // create the new entry
    query::send (qu, "insert into pageitems (ID, active, leftPos, topPos, rightPos, bottomPos) values (?, 3, ?, ?, ?, ?)");
    query::input (qu, kInt, id);
    query::input (qu, kFloat, l);
    query::input (qu, kFloat, t);
    query::input (qu, kFloat, r);
    query::input (qu, kFloat, b);
    query::exec (qu);

    // store snippet
    strcat (path, ".idms");
    query::send (qu, "update pageitems set data = ?, preview = ?, format = 3 where ID = ?");
    query::input (qu, kBinfile, path, kCopyLocalFile, "PICT");
    query::input (qu, kImage, img);
    query::input (qu, kInt, id);
    query::exec (qu);

    // clean up
    query::close (qu);
    image::release (img);
    itemlist::release (frames);
    file::remove (path);

    return 0;
}

Version 1.4 R323, 22. Masr. 2007 InDesign®-Snippets since v3.2.3 R2485, 1. Jun 2011

priint:comet InDesign® Plug-Ins

static int itemlist::align(ItemList frames, int alignHow)

Align a list of frames.

Name Type Default Description
Return int   0 or ErrorCode
frames ItemList - frames to align
alignHow int - How to align?

kHAlignLeft
kHAlignCenter
kHAlignRight
kVAlignTop
kVAlignCenter
kVAlignBottom
#include "internal/types.h"

If the scripts frame belongs to a group, all frames of this are aligned. Otherwise align the currently selected document frames. 

#include "internal/types.h"

int main ()
{
    ItemRef		groupRef	= item::alloc ();
    ItemList	frames		= 0;
    int			result;

    if (frame::get_group (gFrame, groupRef) != 0)
    {
        frames = itemlist::selected ();
    }
    else
    {
        frames = itemlist::alloc ();
        frame::group_content (groupRef, frames);
    }

    result = itemlist::align (frames, kHAlignRight);
    wlog ("", "# Align returns %d\n");

    return 0;
}

Version 2.1 R 713, 15. Mai 2008

priint:comet InDesign® Plug-Ins

static int itemlist::sort(
  ItemList frames,
  int howToSort,
  char* scriptTagName = 0)

Sort a list of frames.

Name Type Default Description
Return int   0 or ErrorCode
frames ItemList Frame list to sort  
howToSort int - sorting method, see also linklist::collect

kSortNo
kSortColwise
kSortRowwise
kSortByZOrder
4 Sort by UIDs

5 Sort by sequence numbers (panel 'Template behavior'). Frames should by on one Comet group.

6 Sort by page elements. Frames should by on one page.

7 Since v4.3 R36000] Alphanumeric sorting according to the values of the script tags given in parameter scriptTagName.

You can also view and edit the defined script tags of a frame in the panel Frame Labels.

scriptTagName String or char* 0 Key name of the script tag according to whose value the frames are to be sorted, see frame::get_script_tag. The parameter is only evaluated for howToSort = 7.
#include "internal/types.h"
#include "internal/text.h"

#include "internal/text.h"

int main ()
{
    ItemList	frames	= itemlist::pageframes (1);
    ItemRef		f		= item::alloc ();
    String		s		= string::alloc ();
    int			i;

    wlog ("", "# Before ###############\n");
    for (i = 0; i < itemlist::length (frames); i++)
    {
        itemlist::get (frames, f, i);
        frame::gettext (f, s);
        wlog ("", "Frame %d : '%s'\n", i+1, string::get (s));
    }

    itemlist::sort (frames, kSortByZOrder);

    wlog ("", "# After ###############\n");
    for (i = 0; i < itemlist::length (frames); i++)
    {
        itemlist::get (frames, f, i);
        frame::gettext (f, s);
        wlog ("", "Frame %d : '%s'\n", i+1, string::get (s));
    }

    return 0;
}

In Python the list can be sorted using the standard Python function sort. In the example, the frames of the current document are sorted by their UIDs and then assigned by a corresponding counting number. 

#!py

import comet

def getUID(element):
    return element.getUID()

def main():

    frames = comet.gDocument.getFrames()
    frames.sort (key=getUID)
    for x in range (0,len(frames)):
        frame = frames[x]
        inline_string = f"%!TT{x+1}"
        frame.setText(inline_string)

    return 0

Version 2.1 R 722, 23. Mai 2008
howToSort 6 (Sort by page elements) since v3.3 R2717, 17. Nov. 2011
howToSort 7 (Sort by Script Tag) since v.4.3 R36000, 22. Jan. 2025

priint:comet InDesign® Plug-Ins, comet_pdf

linklist::collect

static int itemlist::get_cometgroup(ItemList frames, int searchHierarchy = 1)

Get the Comet group ID of a list of frames.

Name Type Default Description
Return int   Comet group id or 0, if no or more than one Comet group found.
frames ItemList - List of valid frames
searchHierarchy int 1 If a frame has no Comet group, check its parent(s)?

1 : Yes
0 : No

Version 3.0 R 1500, 26. August 2009

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

frame::get_cometgroup

static int itemlist::are_members_of(
  ItemList frames,
  int groupID,
  int searchHierarchy = 1)

Check whether a given list of frames are members of given Comet group.

Name Type Default Description
Return int   1 if all frames beloging to the given Comet group, 0 otherwise
frames ItemList - List of valid frames to check
groupID int - ID of Comet group
searchHierarchy int 1 If a frame has no Comet group, check its parent(s)?

1 : Yes
0 : No

Version 3.0 R 1500, 26. August 2009

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

frame::is_member_of

static int itemlist::add_to_cometgroup(
  ItemList items,
  int groupID,
  int invalidateView = 0)

Add a list of frames to a Comet group. OId memberships are resolved as follows:

Name Type Default Description
Return int   0 or ErrorCode
frames ItemList - List of valid frames
groupID int - Comet group ID
invalidateView int 0 Invalidate document view? For performance reasons, avoid invalidatings while building products (build, establish)

Version 3.0 R 1500, 26. August 2009

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

frame::add_to_cometgroup

static int itemlist::remove_from_cometgroup(
  ItemList items,
  int groupID,
  int invalidateView = 0)

Remove frames of a list of frames from a given Comet group.

Name Type Default Description
Return int   0 or ErrorCode
frames ItemList - List of valid frames
groupID int - Comet group id

-1 : Do not check membership
otherwise : Remove membership from the given group only
invalidateView int 0 Invalidate document view? For performance reasons, avoid invalidatings while building products (build, establish)

Version 3.0 R 1500, 26. August 2009

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

frame::remove_from_cometgroup

static int itemlist::create_cometgroup(ItemList items, int invalidateView = 0)

Create a new Comet group from the given frame list. Old memberships are overridden.

Name Type Default Description
Return int   Comet group ID of new group
frames ItemList - List of valid frames
invalidateView int 0 Invalidate document view? For performance reasons, avoid invalidatings while building products (build, establish)

Version 3.0 R 1500, 26. August 2009

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

resolve_cometgroup
comet.frame.createCometGroup

static int itemlist::resolve_cometgroup(
  ItemRef docRef,
  int groupID,
  int resolveSubGroups = 0,
  int invalidateView = 0)

Resolve a Comet group. The frames itself are not removed from the document.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Documennt to work on 0 : Current (script) document
groupID int - Comet group id to reslove
resolveSubGroups int 0 Resolve sub groups too?

1 : Yes
0 : No
invalidateView int 0 Invalidate document view? For performance reasons, avoid invalidatings while building products (build, establish)

Version 3.0 R 1500, 26. August 2009

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

frame::remove_from_cometgroup
create_cometgroup
comet.frame.resolveCometGroup

static int itemlist::remove_cometgroup(
  ItemRef docRef,
  int groupID,
  int removeSubGroups = 0)

Remove all frames of a given Comet group from the document. All Comet group notes pointing to this group are are also removed.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Documennt to work on 0 : Current (script) document
groupID int - ID der Comet-Gruppe, die gelöscht werden soll
removeSubGroups int 0 Remove also frames of sub groups?

1 : Yes
0 : No

Version 3.0 R 1500, 26. August 2009

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

frame::remove_from_cometgroup

static int itemlist::remove_items(ItemList frames)

Remove a list of frames from the document.

Name Type Default Description
Return int   0 or ErrorCode
frames ItemList - List of valid frames. All frames must belong to the same document.

Version 3.0 R 1500, 26. August 2009

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

itemlist::remove_cometgroup
frame::remove

static ItemList itemlist::get_cometgroup_members(
  ItemRef docRef,
  int groupID,
  int includeSubGroups = 0)

Get all members of a Comet group.

Name Type Default Description
Return ItemList   List of members. You should delete this list using release.
docRef ItemRef - Document to work on 0 : Current (script) document
groupID int - ID if Comet group
resolveSubGroups int 0 Insert sub frames to the list too?

1 : Yes
0 : No

Version 3.0 R 1500, 26. August 2009

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

create_cometgroup
resolve_cometgroup
comet.frame.getCometGroupMembers

static int itemlist::move_cometgroup_to(
  ItemRef docRef,
  int groupID,
  float left,
  float top,
  int moveSubGroups = 0,
  int newPage = -1)

Move a Comet group to a new (absolute) position. The groups reference point is the top-left corner of the bounding box about all group frames. All frames must belong to the same document spread.

Moving frames to a new page will remove the Cometgroup memeberships from the moved frames. Thereasin for that is, that you do not move complete Cometgroups normally and in this case you will get Cometgroups over more than one page. Since move_cometgroup_to moves complete Cometgroups always, this function will re-create the Cometgroup at the end (since v4.0.5 R19555, 12. Jul 2017).

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document to work on 0 : Current (script) document
groupID int - Comet group id
left float - x position in points relative to the page
top float - y position in points relative to the page
moveSubGroups int - Move sub group members too?

1 : Yes
0 : No
newPage int -1 Move comet group to this page (1-based)

-1 : Do not change page

Version 3.0 R 1500, 26. August 2009
newPage since v3.3 R2717, 17. Nov. 2011

priint:comet InDesign® Plug-Ins, comet_pdf

itemlist::move_cometgroup_by
itemlist::move_to
itemlist::move_by

static int itemlist::move_cometgroup_by(
  ItemRef docRef,
  int groupID,
  float x,
  float y,
  int moveSubGroups = 0)

Move a Comet group by a given value. The groups reference point is the top-left corner of the bounding box about all group frames.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document to work on 0 : Current (script) document
groupID int - Comet group id
left float - x offset in points
top float - y offset in points
moveSubGroups int 0 Move sub group members too?

1 : Yes
0 : No

Version 3.0 R 1500, 26. August 2009

priint:comet InDesign® Plug-Ins, comet_pdf

itemlist::move_cometgroup_to
itemlist::move_to
itemlist::move_by

static int itemlist::move_to(
  ItemList frames,
  float left,
  float top,
  int newPage = -1,
  int allPages = 0,
  int spreadWise = 0)

Move a list of frames to a new (absolute) position. The frames reference point is the top-left corner of the bounding box about all frames.

If the list contains frame from different pages, only the frames of the first page are moved. This is still true for pages of the same spread. If a frame is not located at any page, the nearest page of the spread is used (under CS3 the first page of the spread is used). If the parameter allPages is set to a value > 0, all sublists are moved page-wise at a time.

If you move the frames to a new page, all Comet groups are lost. To move a Comet group to a new page, please use itemlist::move_cometgroup_to.

Name Type Default Description
Return int   0 or ErrorCode
frames ItemList - Valid frame list
left float - x position in points
top float - y position in points
newPage int -1 Move frames to this page (1-based)

-1 : Do not change page
allPages int 0 If the parameter is set to a value > 0, all sublists are moved page-wise at a time, otherwise only the frames of the page of the first frame are moved.
spreadWise int 0 0 : Move frame page by page
Otherwise : Move frames spreadwise

Version 3.0 R 1500, 26. August 2009
newPage since v3.3 R2717, 17. Nov. 2011
allPages seit v4.2 R31770, 20. Oct. 2022
spreadWise seit v4.2 R32580, 20. Mar. 2023

priint:comet InDesign® Plug-Ins, Illustrator

itemlist::move_by
itemlist::move_cometgroup_by
itemlist::move_cometgroup_to

static int itemlist::move_by(
  ItemList frames,
  float x,
  float y)

Move a list of frames by a given offset.

Name Type Default Description
Return int   0 or ErrorCode
frames ItemList - Valid frame list
left float - x offset in points
top float - y offset in points

Version 3.0 R 1500, 26. August 2009

priint:comet InDesign® Plug-Ins, Illustrator

itemlist::move_to
itemlist::move_cometgroup_by
itemlist::move_cometgroup_to

static int itemlist::adapt_to(
  ItemList frames,
  float w,
  float h)

Adapt a list of given frames to a given size. The size of the bounding box around the frames is used as the old size. According to the currently set nails and magnets, the resulting bounding box may differ from the given values w and h.

Name Type Default Description
Return int   0 or ErrorCode
frames ItemList - Frames to adapt
left float - New width in points
top float - New height in points

Version 3.1 R 1540, 17. Sept. 2009

priint:comet InDesign® Plug-Ins

adapt_by
adapt_cometgroup_to
adapt_cometgroup_by

static int itemlist::adapt_by(
  ItemList frames,
  float dx,
  float dy)

Adapt a list of frames by a given size change.

Name Type Default Description
Return int   0 or ErrorCode
frames ItemList - Frames to adapt
x float - Change of width in points
y float - Change of height in points

Resize a master parent page and adjust the frames to fit the new size. 

float	widthMod	= 200.0;
float	heighthMod	= 100.0;

char 	stScriptTemplate [] = "\
var myLP	= gDocRef1.masterSpreads[%d].pages[%d];\
myLP.resize (CoordinateSpaces.INNER_COORDINATES, AnchorPoint.TOP_LEFT_ANCHOR, ResizeMethods.ADDING_CURRENT_DIMENSIONS_TO, [%f, %f]);\
";

int main ()
{
    String		js	= string::alloc ();
    ItemList 	mli	= itemlist::masteritems (0, "A-Musterseite", 2);

    if (gRun > 1) return 0;

    string::set (js, stScriptTemplate,
     				0,				// 0-based master parent spread index
     				1,				// 0-based page index in master parent spread
     				widthMod,		// Width modification in pts
     				heighthMod);	// Height modification in pts
    run_javascript (js, 0, 1, 2, 0, 0, 0, mli);

    itemlist::adapt_by (mli, widthMod, heighthMod);

    return 0;
}

Version 3.1 R 1540, 17. Sept. 2009

priint:comet InDesign® Plug-Ins

adapt_to
adapt_cometgroup_to
adapt_cometgroup_by

static int itemlist::adapt_cometgroup_to(
  ItemRef docRef,
  int cometGroupID,
  float w,
  float h,
  int subElementsToo = 1)

Adapt the frames of a Comet group to a given size. The size of the bounding box around the frames is used as the old size. According to the currently set nails and magnets, the resulting bounding box may differ from the given values w and h.

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

0 : Current (script) document
cometGroupID int - Comet group ID
w float - New width in points
h float - New height in points
subElementsToo int 1 Adapt sub group elements too?

1 : Yes
0 : No

Version 3.1 R 1540, 17. Sept. 2009

priint:comet InDesign® Plug-Ins

adapt_by
adapt_to
adapt_cometgroup_by

static int itemlist::adapt_cometgroup_by(
  ItemRef docRef,
  int cometGroupID,
  float x,
  float y,
  int subElementsToo = 1)

Adapt the frames of a Comet group by a given size change.

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

0 : Current (script) document
cometGroupID int - Comet group ID
w float - Change with by (in points)
h float - Change with by (in points)
subElementsToo int 1 Adapt sub group elements too?

1 : Yes
0 : No

Version 3.1 R 1540, 17. Sept. 2009

priint:comet InDesign® Plug-Ins

adapt_by
adapt_to
adapt_cometgroup_to

static int itemlist::apply_layout_rules(ItemList frames, int what)

Apply the layout rules for a given list of frames. If the requested type of layout rules is turned off by system::suppres_layoutrules or by the plugins, the rules are not executed.

Name Type Default Description
Return int   0 or ErrorCode
frames ItemList - List of valid document frames
what int - Type of rules to apply?
Icon ValueSituation
2 after load
1 after create
32 after built
4 page reorganization
8 after geometry changes

Version 3.1, R1550, 18. Sept. 2009

priint:comet InDesign® Plug-Ins, comet_pdf

system::suppress_layout_rules
system::wakeup_layout_rules
frame::apply_layout_rules

static int (
  ItemRef outMSO,
  ItemList states,
  int type = 0,
  char* name = "")

DEPRECATED! Please use the function interactive::create_multistate instead.

Name Type Default Description
Return int   0 or ErrorCode

Please use the function interactive::create_multistate instead.

static int itemlist::revert(ItemList frames)

Revert a given ItemList.

Name Type Default Description
Return int   0 or ErrorCode
frames ItemList - List of ItemRefs

v3.3 R2670, 14. Okt. 2011

priint:comet InDesign® Plug-Ins, comet_pdf

static int itemlist::store_magnet_distances(ItemList frames)

Save magnet distances of all frames and all reachable frames of a given list.

Name Type Default Description
Return int   0 or ErrorCode
frames ItemList - List of ItemRefs

Save all magnet distances of the document. 

int main ()
{
    int			pg		= document::pages ();
    int			p;
    ItemList	frames	= 0;

    for (p = 1; p <= pg; p++)
    {
        frames	= itemlist::pageframes (p, 1);
        itemlist::store_magnet_distances (frames);
        itemlist::release (frames);
        frames	= 0;
    }

    return 0;
}

v3.3 R850, 29.03.2012

priint:comet InDesign® Plug-Ins, comet_pdf

frame::store_magnet_distances

static int itemlist::duplicate(
  ItemList resultList,
  ItemList srcList,
  float x,
  float y,
  ItemRef docRef = 0,
  int pageNum = -1,
  char* layerName = "",
  int addToCometgroup = 0,
  int reconstruct = 0)

Duplicate a list of existing document frames. Duplicating is allowed between different opened documents.

If the list contains frame from different pages, only the frames of the first page are moved. This is still true for pages of the same spread. If a frame is not located at any page, the nearest page of the spread is used (under CS3 the first page of the spread is used).

Name Type Default Description
Return int   0 or ErrorCode
resultList ItemList - Newly created frames

0 : Not interested in
otherwise : with itemlist::alloc allocated list for the new frames
srcList ItemList - Valid frame references
x, y float - page relative position of the new frame in points
docRef ItemRef 0 destination document

0 : current front document
pageNum int -1 destination page (1-based)
-1 : same page like originals
layerName String or char* "" Destination layer
"" : layer of first entry of the list
addToCometgroup int 0 Add the new frames to the Comet group of the originals? All frames must be a member of the same group in this case. Comet notes are ignored to determine the Comet group here.

0 : No
1 : Yes. If you duplicate into an other document, the parameter has no effect!
reconstruct int 0 Try to rebuild Comet groups

0 : No. The new frames does not belong to any Comet group

1 : Create Comet groups like in the original frames

If the parameter addToCometgroup is set, this parameter is the winner!}. 
int main ()
{
    int			res;
    ItemRef		resref	= item::alloc ();

    res = frame::duplicate (resref, gFrame, 10.0, 10.0);
    wlog ("", "duplicate result : %d (%d --> %d)\n",
     	res, item::getint (gFrame), item::getint (resref));

    return 0;
}

Copy the frames of page 3 of a document to the current front page. 

int main ()
{
    ItemRef			d1		= document::alloc ("$DESKTOP/base.indd");
    ItemList		src		= itemlist::pageframes_of_doc (d1, 3);
    ItemList		added	= itemlist::alloc ();

    itemlist::duplicate (0, src, 10.0, 20.0);

    return 0;
}

v3.3 R2851, 12. Apr. 2012
Parameter addToCometgroup since version v3.3 R3008, 23. May 2012
Parameter reconstruct since version v3.4, R5322, 19. May 2014

priint:comet InDesign® Plug-Ins

static int itemlist::scale(
  ItemList frames,
  float xscale,
  float yscale,
  float refpointX = 0.0,
  float refpointY = 0.0,
  int suprRules = 1)

Scale a list of frames.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - List of frames
xscale float - x-factor of scaling (1.0 is 100%)
yscale float - y-factor of scaling (1.0 is 100%)
refpointX float 0.0 X value of the fix point in points relative to the left edge of the bounding box of the frames
refpointY float 0.0 Y value of the fix point in points relative to the left edge of the bounding box of the frames
suprRules int 1 Suppres layout rules "After geometry changes" while executing the command?

1 : Yes, suppress rules "after geometry" changes.

0 : No, execute this rules if any. In case rules may triggered while building products too. This may cause problems and/or side effects.

Duplicate a list of frames from one document to an other and scale the new frames. 

int main ()
{
    ItemRef			d1		= document::alloc ("$DESKTOP/schräge Tabellenköpfe.indd");
    ItemRef			d2		= document::alloc ("Unbenannt-1");
    ItemList		src		= itemlist::pageframes_of_doc (d1, 3);
    ItemList		added	= itemlist::alloc ();
    float			l, t, r, b;

    itemlist::duplicate (added, src, 10.0, 20.0);
    itemlist::bbox (added, &l, &t, &r, &b);
    itemlist::scale (added, 0.5, 0.25, (r-l)/2.0, (b-t)/2.0);

    return 0;
}

v3.3 R2851, 12. Apr. 2012
Parameter suprRules since v3.3 R3405, 5. Feb. 2012

priint:comet InDesign® Plug-Ins

static int itemlist::rotate(
  ItemList frames,
  float angle,
  float refpointX = 0.0,
  float refpointY = 0.0,
  int suprRules = 1)

Rotate a list of frames.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - List of frames
angle float - angle to rotate in degrees
refpointX float 0.0 X value of the fix point in points relative to the left edge of the bounding box of the frames
refpointY float 0.0 Y value of the fix point in points relative to the left edge of the bounding box of the frames
suprRules int 1 Suppres layout rules "After geometry changes" while executing the command?

1 : Yes, suppress rules "after geometry" changes.

0 : No, execute this rules if any. In case rules may triggered while building products too. This may cause problems and/or side effects.

Duplicate a list of frames from one document to an other and rotate the new frames. 

int main ()
{
    ItemRef			d1		= document::alloc ("$DESKTOP/schräge Tabellenköpfe.indd");
    ItemRef			d2		= document::alloc ("Unbenannt-1");
    ItemList		src		= itemlist::pageframes_of_doc (d1, 3);
    ItemList		added	= itemlist::alloc ();
    float			l, t, r, b;

    itemlist::duplicate (added, src, 10.0, 20.0);
    itemlist::bbox (added, &l, &t, &r, &b);
    itemlist::rotate (added, 45.0, (r-l)/2.0, (b-t)/2.0);

    return 0;
}

v3.3 R2851, 12. Apr. 2012
Parameter suprRules since v3.3 R3405, 5. Feb. 2012

priint:comet InDesign® Plug-Ins

static int itemlist::skew(
  ItemList frames,
  float angle,
  float refpointX = 0.0,
  float refpointY = 0.0,
  int suprRules = 1)

Skew a list of frames.

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - List of frames
angle float - angle to skew in degrees
refpointX float 0.0 X value of the fix point in points relative to the left edge of the bounding box of the frames
refpointY float 0.0 Y value of the fix point in points relative to the left edge of the bounding box of the frames
suprRules int 1 Suppres layout rules "After geometry changes" while executing the command?

1 : Yes, suppress rules "after geometry" changes.

0 : No, execute this rules if any. In case rules may triggered while building products too. This may cause problems and/or side effects.

Duplicate a list of frames from one document to an other and skew the new frames. 

int main ()
{
    ItemRef			d1		= document::alloc ("$DESKTOP/schräge Tabellenköpfe.indd");
    ItemRef			d2		= document::alloc ("Unbenannt-1");
    ItemList		src		= itemlist::pageframes_of_doc (d1, 3);
    ItemList		added	= itemlist::alloc ();
    float			l, t, r, b;

    itemlist::duplicate (added, src, 10.0, 20.0);
    itemlist::bbox (added, &l, &t, &r, &b);
    itemlist::skew (added, 30.0, (r-l)/2.0, (b-t)/2.0);

    return 0;
}

v3.3 R2851, 12. Apr. 2012
Parameter suprRules since v3.3 R3405, 5. Feb. 2012

priint:comet InDesign® Plug-Ins

static int itemlist::rmv_magnets(ItemList frames, int full_closure = 0)

Remove all nails, magnets and adapter script from all frames of a given list.

Please note that magnets are fixed automatically after layout rules. To apply the magnets in this situation, please follow this steps

  1. Append the rule "Apply magnets" to every frame with size and/or position changes triggered by any of its rules.
  2. Give every frame of step 1 an unique frame label (Kennung).
  3. Add a rule to remove the magnets to the frame with the biggest script label.
If you do not want set or change script labels for every frame, take one suitable frame and give it the label '∞'. The rules of this frame are executed after all other rules in this case. In this frame you can remove the nailsThis will cause executing the rules of this frame

Name Type Default Description
Return int   0 or ErrorCode
frameList ItemList - valid frame list
full_closure int 0 0 : only the frames of the list are changed

otherwise : Clean magnets in all frame available by magnets from any of the frames given in the list

Remove all nails and magnets from a comet group 

int main ()
{
    int			gid		= frame::get_cometgroup (gFrame);
    ItemList	members	= itemlist::get_cometgroup_members (0, gid);

    itemlist::rmv_magnets (members, 1);
    itemlist::release (members);
    return 0;
}

v3.4 R5356, 2. Jul 2014

priint:comet InDesign® Plug-Ins, comet_pdf

frame::rmv_magnets

static int itemlist::write_frame_info(
  ItemRef document,
  int cometGroupID,
  int frameSearchFlags,
  int documentType,
  int conflictBehavior,
  int frameType = 0,
  LinkList placeholders = 0)

Store information about a frame group to the data sources. More information at Frame infos

Name Type Default Description
Return int   0 or ErrorCode
document ItemRef - Document
cometGroupID int - ID of the comet group
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 0 Frame type to write
0: All
1: Text frame
2: Graphic frame
placeholders LinkList 0 Only respect placeholders in this list
#include "internal/frameinfos.h"

Write all frame info of a certain comet group 

int main ()
{
    int cometGroupID = 220;

    return itemlist::write_frame_info(gDocument, cometGroupID);
}

v4.0.5 R8423

priint:comet InDesign® Plug-Ins, comet_pdf

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

static int itemlist::write_frame_info2(
  ItemRef document,
  ItemList frameList,
  int frameSearchFlags,
  int documentType,
  int conflictBehavior,
  int frameType = 0,
  LinkList placeholders = 0)

Write all information about a frame list to the data sources. Works like itemlist::write_frame_info, but accepts a frame list instead of a group ID. More information at Frame infos

Name Type Default Description
Return int   0 or ErrorCode
document ItemRef - Document
frameList ItemList - List of the frames to write
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
#include "internal/frameinfos.h"

Write all frame info of the document 

int main ()
{
    ItemList frames = itemlist::allframes();

    return itemlist::write_frame_info2(gDocument, frames);
}

v4.0.5 R8423

priint:comet InDesign® Plug-Ins, comet_pdf

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

static int itemlist::apply_frame_info(
  ItemRef document,
  int cometGroupID,
  int propertyFlags,
  int searchType,
  int documentType,
  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
cometGroupID int - ID of the comet group
propertyFlags int - Which information should be restored?
See frame::apply_frame_info
frameSearchFlags int - How should the stored frame be identified?
See frame::apply_frame_info
documentType int - How should the document source be identified?
See frame::apply_frame_info
conflictBehavior int kThrowError Behavior when multiple search results are found per frame
See frame::apply_frame_info
frameType int 0 Only respect frames of type
0: All
1: Text frame
2: Graphic frame
placeholders LinkList 0 Only respect placeholders in this list
#include "internal/frameinfos.h"

v4.0.5 R8423

priint:comet InDesign® Plug-Ins, comet_pdf

frame::apply_frame_info
itemlist::apply_frame_info

static int itemlist::apply_frame_info2(
  ItemRef document,
  ItemList frameList,
  int propertyFlags,
  int searchType,
  int documentType,
  int frameType = 0,
  LinkList placeholders = 0)

Restore saved information about a frame from the data sources and set it back to the frames. Works like itemlist::apply_frame_info, but accepts a frame list instead of a group ID. More information at Frame infos

Name Type Default Description
Return int   0 or ErrorCode
document ItemRef - Document
frameList ItemList - List of the frames to be restored
propertyFlags int - Which information should be restored?
See frame::apply_frame_info
frameSearchType int - How should the document source be identified?
See frame::apply_frame_info
documentType int - 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
#include "internal/frameinfos.h"

v4.0.5 R8423

priint:comet InDesign® Plug-Ins, comet_pdf

frame::apply_frame_info
itemlist::apply_frame_info

static int itemlist::delete_frame_info(
  ItemRef docRef,
  int cometGroupID,
  int frameSearchFlags = kUseDefault,
  int documentType = kLocalDoc,
  int conflictBehavior = kThrowError,
  int frameType = 0,
  LinkList placeholders = 0)

Delete frame infos for all frames of a comet group from the data sources. More information at Frame infos

Name Type Default Description
Return int   0 or ErrorCode
document ItemRef - Document
cometGroupID int - ID of the comet group for which the frame infos should be deleted
frameSearchFlags int kUseDefault How should the stored frame be identified?
See frame::apply_frame_info
documentType int kLocalDoc How should the document source be identified?
See frame::apply_frame_info
conflictBehavior int kThrowError Behavior when multiple search results are found per frame
See frame::apply_frame_info
frameType int 0 Only respect frames of type
0: All
1: Text frame
2: Graphic frame
#include "internal/frameinfos.h"

Delete frame infos of a comet group from the data sources 

#include "internal/frameinfos.h"

int main ()
{
    int groupID = 220;

    itemlist::delete_frame_info(gDocument, 220);
    return 0;
}

v4.0.5 R8650

priint:comet InDesign® Plug-Ins, comet_pdf

frame::delete_frame_info
itemlist::delete_frame_info2
document::delete_frame_info

static int itemlist::delete_frame_info2(
  ItemRef docRef,
  ItemList frameList,
  int frameSearchFlags = kUseDefault,
  int documentType = kLocalDoc,
  int conflictBehavior = kThrowError)

Delete frame infos for a list of frames from the data sources. More information at Frame infos

Name Type Default Description
Return int   0 or ErrorCode
document ItemRef - Document
frameList ItemList - List of frames for which the frame infos should be deleted
frameSearchFlags int kUseDefault How should the stored frame be identified?
See frame::apply_frame_info
documentType int kLocalDoc How should the document source be identified?
See frame::apply_frame_info
conflictBehavior int kThrowError Behavior when multiple search results are found per frame
See frame::apply_frame_info
#include "internal/frameinfos.h"

v4.0.5 R8650

priint:comet InDesign® Plug-Ins, comet_pdf

frame::delete_frame_info
itemlist::delete_frame_info
document::delete_frame_info

static int itemlist::convert_to_trailer(int* importer, ItemList frames)

Register frames added by the Build Support as to be a product trailer.

The function can only be called in situation kCheckSizeBefore of Build Supports. You must make sure that there is enough place for the current product at the current page!

Name Type Default Description
Return int   0 or ErrorCode
importer int* - Current building process. Get this value from gImporter of your build support script
frames ItemList - Added frames
#include "internal/types.h"

Add an additional template at the beginning of every N:1 element. The example is sensefull only for N:1 elements! 

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

int main ()
{
    int			result		= 0;
    ItemList	inserted	= 0;

    while (1)
    {
        if (gSituation == kCheckSizeBefore)
        {
            if (gGridPosX == 0.0 && gGridPosY == 0)
            {
                inserted = document::place_items (0,
                 	 "", "",
                 	 178,
                 	 gElementLeft,
                 	 gElementTop,
                 	 gPageNum,
                 	 "",
                 	 gRecordID, gRecordID2, gRecordID3, gRecordStringID,
                 	 1);
                itemlist::convert_to_trailer (gImporter, inserted);
                itemlist::release (inserted);
            }
        }

        break;
    }

    return result;
}

With a little change you can use the above script to add the template to every new page. In this version, the example will work for any type of page elements. 

if (gElement == 1 && gGridPosX == 0.0 && gGridPosY == 0) // Nur erstes Seitenelement

v4.0.5 R18348, 31. May 2017

priint:comet InDesign® Plug-Ins comet_pdf

static int itemlist::pdf_export(
  ItemList frameList,
  char* profile,
  char* outputPath,
  char* outputName,
  float margin = 0.0)

Creates a PDF of the provided frame list using the specified pdf profile. The PDF is cropped to the bounding box of the provided frame list and contains no other frame. Further frames of a text continuation chain are automatically exported aswell. Each page/spread is exported to a separate file in the target folder and is suffixed with a three-digit number (000, 001, 002, ...).

Name Type Default Description
Return int   0 or ErrorCode
frameList ItemList - List of the frames to be exported
profile String or char* - PDF-Exportprofile
outputPath String or char* - Target folder (without file name)
outputName String or char* - Target file name (without extension)
Is suffixed per page/spread (000, 001, ...)
margin float 0.0 Expands the exported area in all directions (unit pt)

PDF-Export for all selected frames 

int main ()
{
    char	* 	pdf_preset = "[Qualitativ hochwertiger Druck]";
    char	* 	outputPath = "c:/temp/banana";
    char	* 	outputName = "bananas";
    ItemList 	frames 		= itemlist::selected();

    if (gRun > 1)
    {
        return 0;
    }

    itemlist::pdf_export(frames, pdf_preset, outputPath, outputName, 10.0);
    itemlist::release(frames);

    return 0;
}

v4.0.5 R8405

priint:comet InDesign® Plug-Ins

document::pdf_export

static ItemList itemlist::linked_urls(ItemRef docRef)

Get all frames of the given document, linked against an Web Images. General information about Web Images can be found here.

Name Type Default Description
Return ItemList   New ItemList containing only frames from inList with Web Images. Must be deleted using itemlist::release!
inList ItemList - Valid iist of frames

Get the currently selected Web Images 

int main()
{
    ItemList 		selected 		= itemlist::selected();
    ItemList 		linked 			= itemlist::linked_urls(selected);
    ItemList 		embedded 		= itemlist::embedded_urls(selected);
    int 			framesCount 	= itemlist::length(selected);
    int 			linkedCount 	= 0;
    int 			embeddedCount 	= 0;

    if (gRun > 1) {
        return 0;
    }

    if (linked) {
        linkedCount = itemlist::length(linked);
    }

    if (embedded) {
        embeddedCount = itemlist::length(embedded);
    }

    showmessage("%d frames selected\n%d are linked\n%d are embedded", framesCount, linkedCount, embeddedCount);

    itemlist::release(selected);
    if (linked) {
        itemlist::release(linked);
    }
    if (embedded) {
        itemlist::release(embedded);
    }

    return 0;
}

v4.0.5 R20002 (28. Jul 2017)

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

frame::has_linked_url
itemlist::embedded_urls
document::linked_urls

static ItemList itemlist::embedded_urls(ItemRef docRef)

Get all frames of the given document with 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 inList with embedded Web Images. Must be deleted using itemlist::release!
inList ItemList - Valid frame list

v4.0.5 R19777 (24. Jul 2017)

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

frame::has_embedded_url
itemlist::linked_urls
document::embedded_urls

static int itemlist::link_urls(ItemList frames, StringList urls)

Link the provided frames to the given Web Images. General information about Web Images can be found here.. Both input lists frames and urls have to be equal in length.

Name Type Default Description
Return int   0 or ErrorCode
frames ItemList - List of frames to be linked.
urls StringList - List of URLs

Link six frames to six images (in this example the document has to have exactly six frames so the lists are equal in length) 

int main()
{
    StringList 	URLs 	= stringlist::alloc();
    ItemList 	frames 	= itemlist::allframes();

    stringlist::append(URLs, "https://priint.com/assets/template/img/priint.png");
    stringlist::append(URLs, "http://imgsv.imaging.nikon.com/lineup/lens/zoom/normalzoom/af-s_dx_18-140mmf_35-56g_ed_vr/img/sample/sample1_l.jpg");
    stringlist::append(URLs, "http://imgsv.imaging.nikon.com/lineup/lens/zoom/normalzoom/af-s_dx_18-140mmf_35-56g_ed_vr/img/sample/sample2_l.jpg");
    stringlist::append(URLs, "http://imgsv.imaging.nikon.com/lineup/lens/zoom/normalzoom/af-s_dx_18-140mmf_35-56g_ed_vr/img/sample/sample3_l.jpg");
    stringlist::append(URLs, "http://imgsv.imaging.nikon.com/lineup/lens/zoom/normalzoom/af-s_dx_18-140mmf_35-56g_ed_vr/img/sample/sample4_l.jpg");
    stringlist::append(URLs, "http://imgsv.imaging.nikon.com/lineup/lens/zoom/normalzoom/af-s_dx_18-140mmf_35-56g_ed_vr/img/sample/sample5_l.jpg");

    itemlist::link_urls(frames, URLs);

    stringlist::release(URLs);
    itemlist::release(frames);

    return 0;
}

v4.0.5 R19777 (24. Jul 2017)

priint:comet InDesign® Plug-Ins, comet_pdf

frame::link_url

static int itemlist::embed_urls(ItemList frames, StringList urls)

Link the provided frames to the given images in the web for embedding. General information about Web Images can be found here.. Both input lists frames and urls have to be equal in length.

Name Type Default Description
Return int   0 or ErrorCode
frames ItemList - List of frames to be linked for embedding.
urls StringList - List of URLs

Link six frames to six images (in this example the document has to have exactly six frames so the lists are equal in length) 

int main()
{
    StringList 	URLs 	= stringlist::alloc();
    ItemList 	frames 	= itemlist::allframes();

    stringlist::append(URLs, "https://priint.com/assets/template/img/priint.png");
    stringlist::append(URLs, "http://imgsv.imaging.nikon.com/lineup/lens/zoom/normalzoom/af-s_dx_18-140mmf_35-56g_ed_vr/img/sample/sample1_l.jpg");
    stringlist::append(URLs, "http://imgsv.imaging.nikon.com/lineup/lens/zoom/normalzoom/af-s_dx_18-140mmf_35-56g_ed_vr/img/sample/sample2_l.jpg");
    stringlist::append(URLs, "http://imgsv.imaging.nikon.com/lineup/lens/zoom/normalzoom/af-s_dx_18-140mmf_35-56g_ed_vr/img/sample/sample3_l.jpg");
    stringlist::append(URLs, "http://imgsv.imaging.nikon.com/lineup/lens/zoom/normalzoom/af-s_dx_18-140mmf_35-56g_ed_vr/img/sample/sample4_l.jpg");
    stringlist::append(URLs, "http://imgsv.imaging.nikon.com/lineup/lens/zoom/normalzoom/af-s_dx_18-140mmf_35-56g_ed_vr/img/sample/sample5_l.jpg");

    itemlist::embed_urls(frames, URLs);

    stringlist::release(URLs);
    itemlist::release(frames);

    return 0;
}

v4.0.5 R19777 (24. Jul 2017)

priint:comet InDesign® Plug-Ins, comet_pdf

frame::embed_url
itemlist::link_urls

static int itemlist::check_url_links(
  ItemList frames,
  ItemList outdated,
  ItemList error,
  int flags)

Check the state of the Web Images of a frame list. General information about Web Images can be found here..

Name Type Default Description
Return int   0 or ErrorCode
frames ItemList - List of frames to be checked.
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 1: Show progress bar

v4.0.5 R19777 (24. Jul 2017)

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

frame::check_url_link
document::check_url_links

static int itemlist::update_url_links(ItemList frames, int flags)

If neccessary, reload the Web Images of a list of frames. General information about Web Images can be found here. Please also note the rules for image placements of Web Images.

Name Type Default Description
Return int   0 or ErrorCode
frames ItemList - List of frames to be updated.
flags int 0 1: Show progress bar

v4.0.5 R19777 (24. Jul 2017)

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

frame::update_url_link
document::update_url_links

static int itemlist::remove_url_links(ItemList frames)

Remove the Web Image links from a list of frames. The images itself are left untouched, only the Web addresses (URLs) are removed. General information about Web Images can be found here..

Name Type Default Description
Return int   0 or ErrorCode
frames ItemList - List of frames to remove the URL links from

v4.0.5 R19777 (24. Jul 2017)

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

frame::remove_url_link
document::remove_url_links

static int itemlist::relink(
  ItemList frames,
  int mappingFunction,
  int reloadPlaceholders = 0)

Find all placeholders in a frame list and relinks them to a new ID

This function searches all placeholders in a frame list and relinks the placeholders to a new ID using the function provided as parameter.

The mapping function must match the following signature: 

int myMappingFunction(IDType in, IDType out);
The following rules apply

Name Type Default Description
Return int   0 or error code
frames ItemList - frames to relink
mappingFunction int - callback function for ID mapping
reloadPlaceholders int 0 reload placeholders after relinking (1) or not (0)

Change the ID1 of all placeholders of a frame list, if not equals 1: 

int normalizeId1(IDType in, IDType out)
{
    if (idtype::id(in) != 1)
    {
        idtype::set_id(out, 1);
        return 1;
    }
    return 0;
}

int main()
{
    ItemList 		selectedFrames = 0;

    if (gRun > 1) return 0;

    selectedFrames = itemlist::selected();
    itemlist::relink(selectedFrames, mapIds);
    itemlist::release(selectedFrames);

    return 0;
}

4.1.7 R26777
product::relink

Since
Plugin Version 1.0.18
Version
24.04.2025, 13:54 Uhr
Author
Paul Seidel
See Also
frame
item

Alphabetic index HTML hierarchy of classes or Java