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

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

static ItemList alloc()

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

Since

Version 1.2 (21 July 2005)

Available

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

static 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

Preconditions

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

Since

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)

Available

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

See Also

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

static 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

Since

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

Available

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

See Also

allframes
comet.CDocument.getFrames

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

Since

since Version 1.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

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

comet.CPage.getFrames

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

Since

v3.3 R2851, 12.04.2012

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

comet.CPage.getFrames

static 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

Since

since Version 1.4 R335 (16. Apr. 2007)

Available

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

See Also

comet.CFrame.getChainFrames

static 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

Since

Version 3.1 R1723, 3. Feb. 2010

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

static 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 placholdered frames? 0 : All frames 1 : Only frames with placeholder
id.., sid	int, String or char*	0	Frame must linked with the given object. Ignored if all values are 0.
info1, info2	String or char*	0	Info1 and Info1 of frame placeholder. Ignored if empty.

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. Be care with the 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;
}

Since

Version 2.1, R1760, 20.02.2010

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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.

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

Since

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

Available

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

See Also

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

static 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

Preconditions

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

Since

Version 2.1 R2200, 28. 10. 2010

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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

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

Since

v4.1.8 R29140, 21. Sep 2021

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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

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

Since

v4.2 R32080, 2. Jan 2023

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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

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

Preconditions

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

Since

v4.2 R32080, 2. Jan 2023

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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

static 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

Preconditions

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

Since

v4.2 R32080, 2. Jan 2023

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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

static 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

Preconditions

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

Since

v4.2 R32080, 2. Jan 2023

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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

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

Since

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

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

itemlist::subframes_of_list

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

Since

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

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

itemlist::subframes_of_list

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

Since

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

Available

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

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

Since

Available

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

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

Since

Available

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

See Also

item::alloc
itemlist::count

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

Since

Available

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

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

Since

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

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

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

Since

1.2.1 (25 August 2005)

Available

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

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

Since

1.2.1 (25 August 2005)

Available

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

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

Since

1.2.1 (25 August 2005)

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

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

Since

1.2.1 (25 August 2005)

Available

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

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

Since

1.2.1 (25 August 2005)

Available

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

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

Since

1.2.1 (25 August 2005)

Available

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

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

Since

1.2.1 (25 August 2005)

Available

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

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

Since

Version 1.2.1 (30 August 2005)

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

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

Preconditions

#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, ...);

Since

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

logical_groups

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

Preconditions

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

Since

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

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

Preconditions

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

Since

Version 1.4 R320 (2. March 2007)

Available

priint:comet InDesign^® Plug-Ins

See Also

itemlistlist
ItemListList
allframes
pageframes
selected

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

Preconditions

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

Since

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

Available

priint:comet InDesign^® Plug-Ins

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

Preconditions

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

Since

Version 2.1 R 713, 15. Mai 2008

Available

priint:comet InDesign^® Plug-Ins

static int sort(ItemList frames, int howToSort)

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.

Preconditions

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

Since

Version 2.1 R 722, 23. Mai 2008
howToSort 6 (sort by page elements) since v3.3 R2717, 17. Nov. 2011

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

linklist::collect

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

Since

Version 3.0 R 1500, 26. August 2009

Available

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

See Also

frame::get_cometgroup

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

Since

Version 3.0 R 1500, 26. August 2009

Available

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

See Also

frame::is_member_of

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

• If the parent is a member of the given list too, the parent group is added.
• Otherwise the frames group ID is changed

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)

Since

Version 3.0 R 1500, 26. August 2009

Available

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

See Also

frame::add_to_cometgroup

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

Since

Version 3.0 R 1500, 26. August 2009

Available

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

See Also

frame::remove_from_cometgroup

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

Since

Version 3.0 R 1500, 26. August 2009

Available

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

See Also

resolve_cometgroup
comet.frame.createCometGroup

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

Since

Version 3.0 R 1500, 26. August 2009

Available

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

See Also

frame::remove_from_cometgroup
create_cometgroup
comet.frame.resolveCometGroup

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

Since

Version 3.0 R 1500, 26. August 2009

Available

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

See Also

frame::remove_from_cometgroup

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

Since

Version 3.0 R 1500, 26. August 2009

Available

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

See Also

itemlist::remove_cometgroup
frame::remove

static 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

Since

Version 3.0 R 1500, 26. August 2009

Available

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

See Also

create_cometgroup
resolve_cometgroup
comet.frame.getCometGroupMembers

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

Since

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

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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

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

Since

Version 3.0 R 1500, 26. August 2009

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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

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

Since

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

Available

priint:comet InDesign^® Plug-Ins, Illustrator

See Also

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

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

Since

Version 3.0 R 1500, 26. August 2009

Available

priint:comet InDesign^® Plug-Ins, Illustrator

See Also

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

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

Since

Version 3.1 R 1540, 17. Sept. 2009

Available

priint:comet InDesign^® Plug-Ins

See Also

adapt_by
adapt_cometgroup_to
adapt_cometgroup_by

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

Since

Version 3.1 R 1540, 17. Sept. 2009

Available

priint:comet InDesign^® Plug-Ins

See Also

adapt_to
adapt_cometgroup_to
adapt_cometgroup_by

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

Since

Version 3.1 R 1540, 17. Sept. 2009

Available

priint:comet InDesign^® Plug-Ins

See Also

adapt_by
adapt_to
adapt_cometgroup_by

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

Since

Version 3.1 R 1540, 17. Sept. 2009

Available

priint:comet InDesign^® Plug-Ins

See Also

adapt_by
adapt_to
adapt_cometgroup_to

static int 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 Value Situation 2 after load 1 after create 32 after built 4 page reorganization 8 after geometry changes

Since

Version 3.1, R1550, 18. Sept. 2009

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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

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

Deprecated

Please use the function interactive::create_multistate instead.

static int revert(ItemList frames)

Revert a given ItemList.

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

Since

v3.3 R2670, 14. Okt. 2011

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

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

Since

v3.3 R850, 29.03.2012

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

frame::store_magnet_distances

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

Since

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

Available

priint:comet InDesign^® Plug-Ins

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

Since

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

Available

priint:comet InDesign^® Plug-Ins

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

Since

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

Available

priint:comet InDesign^® Plug-Ins

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

Since

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

Available

priint:comet InDesign^® Plug-Ins

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

Since

v3.4 R5356, 2. Jul 2014

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

frame::rmv_magnets

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

Preconditions

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

Since

v4.0.5 R8423

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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

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

Preconditions

#include "internal/frameinfos.h"

Write all frame info of the document

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

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

Since

v4.0.5 R8423

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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

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

Preconditions

#include "internal/frameinfos.h"

Since

v4.0.5 R8423

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

frame::apply_frame_info
itemlist::apply_frame_info

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

Preconditions

#include "internal/frameinfos.h"

Since

v4.0.5 R8423

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

frame::apply_frame_info
itemlist::apply_frame_info

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

Preconditions

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

Since

v4.0.5 R8650

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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

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

Preconditions

#include "internal/frameinfos.h"

Since

v4.0.5 R8650

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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

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

Preconditions

#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

Since

v4.0.5 R18348, 31. May 2017

Available

priint:comet InDesign^® Plug-Ins comet_pdf

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

Since

v4.0.5 R8405

Available

priint:comet InDesign^® Plug-Ins

See Also

document::pdf_export

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

Since

v4.0.5 R20002 (28. Jul 2017)

Available

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

See Also

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

static 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

Since

v4.0.5 R19777 (24. Jul 2017)

Available

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

See Also

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

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

Since

v4.0.5 R19777 (24. Jul 2017)

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

frame::link_url

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

Since

v4.0.5 R19777 (24. Jul 2017)

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

frame::embed_url
itemlist::link_urls

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

Since

v4.0.5 R19777 (24. Jul 2017)

Available

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

See Also

frame::check_url_link
document::check_url_links

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

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

Since

v4.0.5 R19777 (24. Jul 2017)

Available

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

See Also

frame::update_url_link
document::update_url_links

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

Since

v4.0.5 R19777 (24. Jul 2017)

Available

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

See Also

frame::remove_url_link
document::remove_url_links

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

• during a call of the relink function, the mapping function is called once for each ID found in the frames of the product.
• if in equals out, placeholders linked with this IDs are not relinked
• initially, all values of out are equal to values of in, so only values actually changed must be set to out
• if the function returns 1, the placeholder is relinked. If the function returns 0, the placeholder is not relinked, regardless of the value of out

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

Since

4.1.7 R26777

See Also

product::relink

Author

Paul Seidel

Version

23.05.2023, 08:34 Uhr

Since

Plugin Version 1.0.18

See Also

frame
item

Alphabetic index HTML hierarchy of classes or Java