Placeholder lists.

Here you will find examples to use linklist.

Placeholder lists. The module methods offer the possibility to ceate and change lists of placeholders. With the help of the created lists, document placeholder actions can be triggered (load, store, sync). The results of the actions are stored in the respective list elements.

static LinkList alloc(int intent = 0)

Create a new empty list for working with placeholders. All entries in the list have the same data type Link. Use the parameter intent to specify the context in which the list is to be used. The list must be released again with linklist::release.

Name Type Default Description
Return LinkList   New empty with the given intention. \The list must be released again using linklist::release.

0 : Error while creating the list
intent int 0 Intention (Type) of the list. See here for more information.

Processing of all placeholders for load, store, sync and apply with type = 0 is implemented from version 1.1.6.
linklist::release
Link

static int release(LinkList lli)

Release a list created by linklist::alloc. The function also releases all elements of the list from the memory.

The content of list elements (links) that are still used in the script is invalid after deletion and the use of elements from released lists causes InDesign® resp. comet_pdf to crash.

Also empty lists elements must be released.

Name Type Default Description
Return int   0 or ErrorCode
lli LinkList - List to be deleted.

The content of list elements (links) that are still used in the script is invalid after deletion and the use of elements from released lists causes InDesign® resp. comet_pdf to crash.


priint:comet InDesign® Plug-Ins, comet_pdf

linklist::alloc
Link

static int clear(LinkList lli)

Release and remove all entries from the list. The call is particularly useful for the result lists of sync, as these lists can take up a lot of memory.

To release the list itself, use the function release.

Name Type Default Description
Return int   0 or Error Code
lli LinkList - Valid LinkList


priint:comet InDesign® Plug-Ins, comet_pdf

sync
release

static int type(LinkList lli)

Type (Intention) of list.
Intention Description
0 Unspecified Liste. The lists are filled with collect or collect_any. The values of the elements can then be queried using the functions of Link.
1 ListList with Placeholders. The list elements contain the IDs of placeholders. With insert_placeholder new elements can be inserted into the list. The values of the elements can be queried with link::placeholderid.
2 ListList with products. The list elements contain the IDs of products. With insert_id new elements can be inserted into the list. The values of the elements can be queried with link::id, ... .

Name Type Default Description
Return int   Type (intention) of the list
0 : Unspecified
1 : Placeholder
2 : Products
lli LinkList - Valid LinkList


priint:comet InDesign® Plug-Ins, comet_pdf

alloc

static int length(LinkList lli)

Number of elements in the list.

Name Type Default Description
Return int   Number of elements in the list
lli LinkList - Valid LinkList


priint:comet InDesign® Plug-Ins, comet_pdf

int insert_placeholder(
  LinkList lli,
  int placeholderId,
  KeyValues keyValues,
  int actionType,
  int pos)

Insert a new placeholder ID in a list. The function is valid for placeholder lists or untyped lists only.
This function replaces linklist::insert resp. linklist::insert2 with less than 5 parameters.

Name Type Default Description
Return int   0 or ErrorCode
lli LinkList - Valid LinkList of intention 0 or 1
plID int - ID of a placeholder
keyValues KeyValues 0 ListList of key-value pairs. If the list contains entries, only placeholders are handled which have a set of function variables containing all the specified key/value pairs. To check alternatives, please define multiple entries in the list lli.
actionType int 0 Action defining the function variable value Mandatory, if keyValues are provided Valid values:
  • kInvalidAction (0): all actions
  • kLoadAction (1): load
  • kWriteAction (2): store
  • kSyncAction (3): sync
  • kBuildAction (4): build
position int -1 Insert position. The new element will be inserted before the specified position. List positions are counted beginning with 0.
-1 : Append
#include "internal/types.h"

Fill a list with various placeholder definitions

#include "internal/types.h"
 
int main ()
{
    LinkList	lli	= linklist::alloc (1);	// Placeholder list
    // placeholder with certain ID:
    int err = linklist::insert_placeholder (lli, 123); 
     
    // arbitrary value plus function variable value
    KeyValues keyValues = keyvalues::alloc ("resultEntityId", "name");
    err = linklist::insert_placeholder (lli, 0, keyValues, kLoadAction);
     
    // arbitrary value plus alternative function variable value/span>
    keyvalues::put (keyValues, "resultEntityId", "description");
    err = linklist::insert_placeholder (lli, 0, keyValues, kLoadAction);
     
    \span[c-comment]{// several mandatory function variable values:
        keyvalues::put (keyValues, "resultEntityId", "label");
        keyvalues::put (keyValues, "tag", "useForTableOfContent");
        err = linklist::insert_placeholder (lli, 0, keyValues, kLoadAction);
         
        // ERROR! actionType is mandatory, if keyValues is provided:
        err = linklist::insert_placeholder (lli, 0, keyValues);
         
        // ERROR! invalid actionType:
        err = linklist::insert_placeholder (lli, 0, keyValues, 7);
         
        // valid, but: ID 0 and no keyValues does not match any placeholder:
        err = linklist::insert_placeholder (lli, 0);
         
        // valied, but: ID 0 and empty keyValues does not match any placeholder either:
        keyvalues::clear (keyValues);
        err = linklist::insert_placeholder (lli, 0, keyValues, kLoadAction);
         
        linklist::release (lli);
        keyvalues::release (keyValues);
        return err;
    }

4.1 R21475

priint:comet InDesign® Plug-Ins, comet_pdf

alloc
get

static int insert_id(
  LinkList lli,
  int classid,
  int id,
  int id2 = 0,
  int id3 = 0,
  char* sid = "",
  int position = -1)

Insert a new product (record) ID in a list. Only valid for object lists or untyped lists.

Name Type Default Description
Return int   0 or ErrorCode
lli LinkList - Valid LinkList of type (intention) 0 or 2
classid int - Class number of the placeholder
id int - ID of the object which is linked with the placeholder
id2 int 0 ID2 of the object which is linked with the placeholder
id3 int 0 ID3 of the object which is linked with the placeholder
sid String or char* "" StringID of the object.
position int -1 Insert position. The new element will be inserted before the specified position. List positions are counted beginning with 0.
-1 : Append

4.1 R21475

priint:comet InDesign® Plug-Ins, comet_pdf

alloc
get

static int insert(
  LinkList lli,
  int classid,
  int id = 0,
  int id2 = 0,
  int id3 = 0,
  int position = -1,
  char* sid = "")

Insert a new element in a list. The parameter number of the function must match the list type, placeholder lists have one number, object lists four.

Name Type Default Description
Return int   0 or ErrorCode
lli LinkList - Valid LinkList
⇨ Object list
classid int - Class number of the placeholder
id int - ID of the object which is linked with the placeholder
id2 int - ID2 of the object which is linked with the placeholder
id3 int - ID3 of the object which is linked with the placeholder
position int -1 Insert position. The new element will be inserted before the specified position. List positions are counted beginning with 0.
-1 : Append
sid String or char* "" StringID of the object.
⇨ Placeholder IDs or undefined type
plID int - ID of a placeholder
position int -1 Insert position. The new object will be inserted before the specified position. List positions are counted beginning with 0.
-1 : Append

please use linklist::insert_placeholder or linklist::insert_id instead
Parameter sid from Version 1.3 (Build 96)

priint:comet InDesign® Plug-Ins, comet_pdf

alloc
get
insert_placeholder
insert_id

static int insert2(
  LinkList lli,
  int classid,
  int id = 0,
  int id2 = 0,
  int id3 = 0,
  char* sid = "",
  int position = -1)

Like insert, but with a changed parameter sequence. The stringID comes directly after the three objectIDs.

Name Type Default Description
Return int   0 or ErrorCode
lli LinkList - Valid LinkList
⇨ Object list
classid int - Class number of the placeholder
id int - ID of the object which is linked with the placeholder
id2 int - ID2 of the object which is linked with the placeholder
id3 int - ID3 of the object which is linked with the placeholder
sid String or char* "" StringID of the object.
position int -1 Insert position. The new element will be inserted before the specified position. List positions are counted beginning with 0.
-1 : Append
⇨ Placeholder IDs or undefined type
plID int - ID of a placeholder
position int -1 Insert position. The new object will be inserted before the specified position. List positions are counted beginning with 0.
-1 : Append

please use linklist::insert_placeholder or linklist::insert_id instead
Version 1.3 (Build 96)

priint:comet InDesign® Plug-Ins, comet_pdf

insert_placeholder
insert_id

static Link get(LinkList lli, int position)

Get an element of the list. The received element must never be released with link::release.

Name Type Default Description
Return Link   Element at the specified list position or 0
lli LinkList - Valid LinkList
position int - 0-based list position. If the position is -1 or greater than the list length, the final list element will be returned.


priint:comet InDesign® Plug-Ins, comet_pdf

length
Link
link::id
link::sid

static int find(
  LinkList lli,
  int classid,
  int id = 0,
  int id2 = 0,
  int id3 = 0,
  char* sid = "")

Does the list contain an element with the specified values? The (0-based) position of the first element found will be returned. The parameter of the function must match the list type, placeholder lists have one number, product lists four.

Name Type Default Description
Return int   List position or -1
lli LinkList - Valid LinkList
⇨ Object list
classid int - Class number of the placeholder
id int - ID of the object
id2 int - ID2 of the object
id3 int - ID3 of the object
sid String or char* "" StringID of the object.
⇨ Placeholder IDs or undefined type
plID int - ID of a placeholder

Parameter sid since Version 1.3 (Build 96)

priint:comet InDesign® Plug-Ins, comet_pdf

alloc
get
Link
link::id
link::sid

static int remove(
  LinkList lli,
  int classid,
  int id,
  int id2,
  int id3,
  char* sid = "")

Remove the occurrence of an element from a list. References to the deleted element are invalid thereafter. The parameter number of the function must match the list type, placeholders have one number, object lists four.

Name Type Default Description
Return int   0 or ErrorCode
lli LinkList - Valid LinkList
⇨ Object list or undefined type
classid int - Class number of the placeholder
id int - ID of the object
id2 int - ID2 of the object
id3 int - ID3 of the object
sid String or char* "" StringID of the object.
⇨ Placeholder IDs or undefined type
plID int - ID of a placeholder

Fill a list and then delete some entries immediately afterwards

int main ()
{
    int			i	= 0;
    LinkList	lli	= linklist::alloc (2);	// List with product (record) ids
    Link		lk;
// Fill list for (i=1; i<6; i++) linklist::insert (lli, 1, i, i*2, i*3); linklist::insert (lli, 1, 11, 22, 33, 1); linklist::insert (lli, 1, 11, 22, 33, 4);
// Delete all elements <11, 22, 33> from the list linklist::remove (lli, 1, 11, 22, 33);i = 0; for (  lk = linklist::first (lli);   lk != 0;   lk = linklist::next (lli)) { showmessage ("3. Liste %d. Element : %d <%d, %d, %d>",   ++i,   link::classid (lk),   link::id (lk),   link::id2 (lk),   link::id3 (lk)); }
linklist::release (lli); return 0; }

Parameter sid since Version 1.3 (Build 96)

priint:comet InDesign® Plug-Ins, comet_pdf

remove_pos

static int remove_pos(LinkList lli, int position)

Remove the specified element from a list. References to this element are invalid thereafter.

Name Type Default Description
lli LinkList - Valid LinkList
position int - 0-based list position. If the position is -1 or greater than the list length, the final list element will be deleted.


priint:comet InDesign® Plug-Ins, comet_pdf

remove_pos

static Link first(LinkList lli)

Get the first element of a list. If the list is empty or if no other elements are available, the calls will return 0.

Name Type Default Description
Return Link   Found element of the list or 0.
lli LinkList - Valid LinkList
For the next, prev and current calls the list position must be set using first, last or set_pos. Otherwise the calls will deliver no clear result.
The current list position will be changed correspondingly.

Fill a list and go through forward it once.

int main ()
{
    int			i	= 0;
    LinkList	lli	= linklist::alloc (2);	// Object list
    Link		lk;
// Fill list for (i=1; i<6; i++) linklist::insert (lli, 1, i, i*2, i*3); linklist::insert (lli, 1, 11, 22, 33, 1); linklist::insert (lli, 1, 11, 22, 33, 4);
// Write all elements i = 0; for (  lk = linklist::first (lli);   lk != 0;   lk = linklist::next (lli)) { showmessage ("1. Liste %d. Element : %d <%d, %d, %d>",   ++i,   link::classid (lk),   link::id (lk),   link::id2 (lk),   link::id3 (lk)); }
linklist::release (lli); return 0; }

The second example likewise fills a list. Then the list position is set to a certain entry of the list and run through it once.

int main ()
{
    int			i	= 0;
    LinkList	lli	= linklist::alloc (2);	// Object list
    Link		lk;
// Fill list for (i=1; i<6; i++) linklist::insert (lli, 1, i, i*2, i*3); linklist::insert (lli, 1, 11, 22, 33, 1); linklist::insert (lli, 1, 11, 22, 33, 4);
// Fix the list start to the element <3, 6, 9> linklist::set_pos (lli, linklist::find (lli, 1, 3, 6, 9)); i = 0; for (  lk = linklist::current (lli);   lk != 0;   lk = linklist::next (lli)) { showmessage ("2. Liste %d. Element : %d <%d, %d, %d>",   ++i,   link::classid (lk),   link::id (lk),   link::id2 (lk),   link::id3 (lk)); }
linklist::release (lli); return 0; }


priint:comet InDesign® Plug-Ins, comet_pdf

set_pos
next
prev
last
current
next
prev
last
current

static Link next(LinkList lli)

Get the next element of a list. If the list is empty or if no other elements are available, the calls will return 0.

Name Type Default Description
Return Link   Found element of the list or 0.
lli LinkList - Valid LinkList
For the next, prev and current calls the list position must be set before by using first, last or set_pos. Otherwise the calls will deliver no clear result.
The current list position will be changed correspondingly.


priint:comet InDesign® Plug-Ins, comet_pdf

set_pos
first
prev
last
current

static Link prev(LinkList lli)

Get the previous element of a list. If the list is empty or if no other elements are available, the calls will return 0.

Name Type Default Description
Return Link   Found element of the list or 0.
lli LinkList - Valid LinkList
For the next, prev and current calls the list position must be set before by using first, last or set_pos. Otherwise the calls will deliver no clear result.
The current list position will be changed correspondingly.


priint:comet InDesign® Plug-Ins, comet_pdf

set_pos
first
next
last
current

static Link last(LinkList lli)

Get the last element of a list. If the list is empty or if no other elements are available, the calls will return 0.

Name Type Default Description
Return Link   Found element of the list or 0.
lli LinkList - Valid LinkList
For the next, prev and current calls the list position must be set before by using first, last or set_pos. Otherwise the calls will deliver no clear result.
The current list position will be changed correspondingly.


priint:comet InDesign® Plug-Ins, comet_pdf

set_pos
first
next
last
current

static Link current(LinkList lli)

Get the current element of a list. If the list is empty or if no other elements are available, the calls will return 0.

Name Type Default Description
Return Link   Found element of the list or 0.
lli LinkList - Valid LinkList
For the next, prev and current calls the list position must be set before by using first, last or set_pos. Otherwise the calls will deliver no clear result.
The current list position will be changed correspondingly.


priint:comet InDesign® Plug-Ins, comet_pdf

set_pos
first
next
prev
last

static int set_pos(LinkList lli, int position)

Set the current list position. On index errors, current list position is set to 0.

Name Type Default Description
lli LinkList - Valid LinkList
position int - 0-based list position. If the position is < 0 or larger than the list length, the list position is set at the start of the list.
The current position is changed correspondingly.

Fill a list a run it to the end starting from element (1, 3, 6, 9).

int				i	= 0;
LinkList		lli 	= linklist::alloc ();
Link			lk;
for (i=1; i<6; i++) linklist::insert (1, i, i*2, i*3);
i = 0; linklist::set_pos (linklist::find (lli, 1, 3, 6, 9)); for (  lk = linklist::first (lli);   lk != 0;   lk = linklist::next ()) { showmessage ("%d. Element : %d <%d, %d, %d>",   ++i,   link::classid (lk),   link::id (lk),   link::id2 (lk),   link::id3 (lk));


priint:comet InDesign® Plug-Ins, comet_pdf

next
prev
first
last
current

static int load(LinkList lli, int designate = kDesignateDocument)

Reloading linked placeholders of the document. The function executes the load actions of the placeholders found in the specified area.

Name Type Default Description
Return int   0 or ErrorCode
lli LinkList - Valid LinkList of type 1 (placeholder IDs) or 2 (product IDs).

For lists of type 0, any list entries are ignored and all placeholders of the target frames/texts are processed.
⇨ Where in the document are placeholders to be searched for? There are three possibilities.
1. Reload the placeholders of a designated document 'area'

linklist::load (lli)
linklist::load (lli, kDesignateVisibleLayers)
designate int kDesignateDocument Which part of the document is to be processed?

kDesignateCursor
kDesignateSelected
kDesignateDocument
kDesignateVisibleLayers
kDesignateActiveLayer
2. Reload the placeholders of a given frame

linklist::load (lli, 0, gItemRef)
designate int - unused
itemRef ItemRef - Only process these frame.
3. Reload the placeholders of a given text range

linklist::load (lli, -2, 0, 0)
linklist::load (lli, 0, kEnd, gItemRef)
start int - From which text position is the placeholder to be newly loaded? Is the start position within the placeholder, if so, it will be automatically relocated to the start of the placeholder.
>= 0 : Textposition
kSelection : Current text selection. The following length specification will be ignored in this case.
len int - Length of the text the placeholder of which is to be newly loaded. If the end position is within a placeholder, it will be automatically relocated to the end of the placeholder.
>= 0 : Length specification> kEnd : Text end
itemRef ItemRef - 0 : process current text
otherwise process the text of this frame
#include "internal/types.h"
#include "internal/text.h"

Update all type names, family names, names and species identification code in the document.

int main ()
{
    int			i	= 0;
    LinkList	lli	= linklist::alloc (1);	// Placeholder list
    Link		lk;
// Fill list linklist::insert (lli, 1); // Type name linklist::insert (lli, 3); // Family name linklist::insert (lli, 4); // Name linklist::insert (lli, 6); // Species identification code
linklist::load (lli);
linklist::release (lli); return 0; }

Here are a few examples for the use of the parameter to determine the target object

linklist::load (lli);					// Entire document
linklist::load (lli, 1);				// Entire document
linklist::load (lli, 2);				// Current frame selection
linklist::load (lli, 0, frame); // Process this frame linklist::load (lli, 0, kEnd, frame); // Entire text of a frame linklist::load (lli, 0, kEnd, 0); // Entire active text linklist::load (lli, -2, 0, 0); // Current text selectionl
// // The following call cannot be understood : // Use the position of the current text selection // but not necessarily the current text. // linklist::load (lli, -2, 0, frame);

All parameter except lli from Version 1.1.4
The processing of all placeholders (type=0) is implemented from Version 1.1.6.
kDesignateVisibleLayers and kDesignateActiveLayer since version 1.4 R310, 8. Feb. 2007 #include "internal/types.h"
int main() { LinkList lli = linklist::alloc(); // Use an unspecified list here only
linklist::load(lli, kDesignateDocument); linklist::release(lli);
return 0; }

priint:comet InDesign® Plug-Ins, comet_pdf

type
alloc

static int store(LinkList lli)

Write (store) linked placeholders of the document back into the datapool. The function executes the store actions of the placeholders found in the specified area.

Name Type Default Description
Return int   0 or ErrorCode
lli LinkList - Valid LinkList with type = 1 or 2.
With lists of type 0 (mostly used in calls to collect or collect_any) all possible list entries are ignored and for all placeholders the target frames/text processed.
⇨ Where in the document are placeholders to be searched for? There are three possibilities.
1. Store the placeholders of the designated document 'area'

linklist::load (lli)
linklist::load (lli, kDesignateVisibleLayers)
designate int kDesignateDocument Which part of the document is to be processed?

kDesignateCursor
kDesignateSelected
kDesignateDocument
kDesignateVisibleLayers
kDesignateActiveLayer
2. Store the placeholders of a given frame

linklist::load (lli, 0, gItemRef)
designate int - unused
itemRef ItemRef - Only process these frames.
3. Store the placeholders of a given text range

linklist::load (lli, -2, 0, 0)
linklist::load (lli, 0, kEnd, gItemRef)
start int - From which text position is the placeholder to be newly loaded? Is the start position within the placeholder, if so, it will be automatically relocated to the start of the placeholder.
>= 0 : Textposition
kSelection : Current text selection. The following length specification will be ignored in this case.
len int - Length of the text the placeholder of which is to be newly loaded. If the end position is within a placeholder, it will be automatically relocated to the end of the placeholder.
>= 0 : Length specification> kEnd : Text end
itemRef ItemRef - 0 : process current text
otherwise process the text of this frame
#include "internal/types.h"
#include "internal/text.h"

see the examples for load

All parameters except lli from Version 1.1.4
The processing of all placeholders (type=0) is implemented from Version 1.1.6.
kDesignateVisibleLayers and kDesignateActiveLayer since version 1.4 R310, 8. Feb. 2007

priint:comet InDesign® Plug-Ins, comet_pdf

type
load
alloc

static int sync(
  LinkList lli,
  LinkList results,
  int doExec = 0,
  ItemRef frameRef = 0)

heck the sync-styte of linked placeholders of the document. The function executes the sync actions of the placeholders found in the specified area.

Name Type Default Description
Return int   0 or ErrorCode
lli LinkList - Valid LinkList of type 1 (placeholder IDs) or 2 (product IDs).

For lists of type 0, any list entries are ignored and all placeholders of the designated frames/texts are reloaded.
results LinkList - Results list. The results list must be initialised using alloc and is cleared automatically before the execution.
doExec int 0 0 : Determnine the current status the placeholders without prior checkings

1 : Before determining the states the sync actions of the placeholders are executed.
⇨ What document frames are to be processed? With the specification of a frame in the parameter itemRef, the parameter designate is ignored.
designate int kDesignateDocument Which part of the document is to be processed? Will only be evaluated if the parameter itemRef is equal to 0.

kDesignateCursor
kDesignateSelected
kDesignateDocument
kDesignateVisibleLayers
kDesignateActiveLayer
itemRef ItemRef 0 Only process these frame.
#include "internal/types.h"
#include "internal/text.h"
The elements of the entry list signalise with link::sync < 0, that there is no placeholder in the document which correspond to the conditions of the respective element.

Ascertain the placeholder data of all type names, family names, names and species identification code in the document.

int main ()
{
    int			i		= 0;
    LinkList	lli		= linklist::alloc (1);	// Placeholder list
    LinkList	rets	= linklist::alloc (0);	// User-defined list
    Link		lk;
    String		content = string::alloc ();
    char		page[256];
// Fill list linklist::insert (lli, 1); linklist::insert (lli, 3); linklist::insert (lli, 4); linklist::insert (lli, 6); linklist::insert (lli, 12); linklist::insert (lli, 44444);
linklist::sync (lli, rets, 0); for (  lk = linklist::first (rets);   lk;   lk = linklist::next (rets)) { char m[500];
strcpy (m, "Placeholder %d <%d, %d, %d>"); strcat(m, "\n Content : %s"); strcat(m, "\n Status : %d"); strcat(m, "\n Page : %d (%s)"); strcat(m, "\n Position : %d-%d"); strcat(m, "\n Text length : %d");
showmessage (m,   link::placeholderid (lk),   link::id (lk),   link::id2 (lk),   link::id3 (lk),   link::gettext (lk, content),   link::sync (lk),   link::pagenum (lk),   link::pagestr (lk, page),   link::pos (lk)+link::length (lk)   link::textlen (lk)); } linklist::release (rets);
// Placeholder not found for (  lk = linklist::first (lli);   lk;   lk = linklist::next (lli)) { if (link::sync (lk) < 0) { showmessage ("Placeholder %d not found",   link::placeholderid (lk)); } }
linklist::release (lli); string::release (content); return 0; }

itemRef and designate since Version 1.1.4
The processig of all placeholders (type=0) is implemented from Version 1.1.6.
kDesignateVisibleLayers and kDesignateActiveLayer since version 1.4 R310, 8. Feb. 2007

priint:comet InDesign® Plug-Ins

static int apply(
  LinkList lli,
  int actionID,
  int designate)

Execute a specified action for linked placeholders of the document. The function executes the specified action actionID for all placeholders found in the specified area.

Name Type Default Description
Return int   0 or ErrorCode
lli LinkList - alid LinkList of type 1 (placeholder IDs) or 2 (product IDs).

For lists of type 0, any list entries are ignored and all placeholders of the target frames/texts are processed.
actionID int - Valid ID of the database table iQuest.actions. The action can be a script or an SQL instruction.
⇨ Where in the document are placeholders to be searched for? There are three possibilities.
1. Apply action to the placeholders of the designated document 'area'

linklist::load (lli)
linklist::load (lli, kDesignateVisibleLayers)
designate int kDesignateDocument Which part of the document is to be processed?

kDesignateCursor
kDesignateSelected
kDesignateDocument
kDesignateVisibleLayers
kDesignateActiveLayer
2. Apply action to the placeholders of a given frame

linklist::load (lli, 0, gItemRef)
designate int - unused
itemRef ItemRef - Only process these frames.
3. Apply action to the placeholders of a given text range

linklist::load (lli, -2, 0, 0)
linklist::load (lli, 0, kEnd, gItemRef)
start int - From which text position is the placeholder to be newly loaded? Is the start position within the placeholder, if so, it will be automatically relocated to the start of the placeholder.
>= 0 : Textposition
kSelection : Current text selection. The following length specification will be ignored in this case.
len int - Length of the text the placeholder of which is to be newly loaded. If the end position is within a placeholder, it will be automatically relocated to the end of the placeholder.
>= 0 : Length specification> kEnd : Text end
itemRef ItemRef - 0 : process current text
otherwise process the text of this frame
#include "internal/types.h"
#include "internal/text.h"

Analgous to the examples for load

ab Version 1.1.4
The processing of all placeholders (type=0) is implemented from Version 1.1.6.
kDesignateVisibleLayers and kDesignateActiveLayer since version 1.4 R310, 8. Feb. 2007

priint:comet InDesign® Plug-Ins, comet_pdf

type
alloc

static int collect(
  LinkList lli,
  int page = 0,
  char* layer = "",
  int edge = 8,
  int sort = 0,
  ...)

Collect the placeholders linked to a product in a given document area. Placeholders are identified by their placeholder ID and assumed to be linked with an product. To find unlinked placeholders too, use collect_any please. If a frame list is given (layer == "--list--"), unlinked placeholders are collected too. The result list may be sorted column or row wise by thw frame positions.

The function can used in order to find the placeholder lying furthest in a specific page corner. In this case the result list contains a maximum of one result. For the spacing to a corner the sum of the X and Y values of the corresponding frame corners are used : Left upper page corner - upper left of the frame, right upper page corner - upper right of the frame. If the two frames have the same distance, the higher (or lower) frame is used.In the image the red frames is located with this spacing definition at the next to the left upper page corner. If it is removed (or contains a placeholder that is not to be used), the green frames has precedence. While (Green and Blue do have the same spacing to the corner, green is located higher.) The orange frames will not be found. While it is indeed the highest located, it is unfortunately located very much to the right (and that is never good).

Text coordinates calulated by default for all text placeholders (always given in points relative to the top left corner of the text frame.) in this case, placeholder (full or partial) in overset, excluded from the result list. If you need placeholders in overset too, please append the optional placeholder id list by ,0,0 (see last line of the parameters table below.).

Name Type Default Description
Return int   0 or ErrorCode
Return int   0 or ErrorCode
lli LinkList - Valid LinkList with type = 0
page or frames int or itemlist 0 if (layer is not "--list--")
    document page (1-based)
   0 - current page

if (layer = "--list--")
    list of valid document frames

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

layer String or char* "" Limit search to the specified layer
"" : all layers
"--visible--" : visible layers only
"--active--" : active layer only
"--list--" : second parameter points to a list of document frames
edge int kFirstIgnore Find all placeholders of placeholder of a specified corner

kFirstIgnore - all placeholders
kFirstLeftTop
kFirstRightTop
kFirstOuterTop - left pages left upper corner, right pages right upper corner
kFirstInnerTop - left pages right upper corner, right pages left upper corner
kFirstLeftBottom
kFirstRightBottom
kFirstOuterBottom - left pages left bottom corner, right pages right bottom corner
kFirstInnerBottom - left pages right bottom corner, right pages left bottom corner
sort int kSortNo Sort the results list

kSortNo - Do not sort

kSortColwise - sorted according to left frame edge from top to bottom. In the image above there results
  blue
  red
  green
  orange

kSortRowwise - sorted from left to right by top of the frame. With the figure above, the following sort order results
  orange
  red
  green
  blue

kSortByZOrder - Frames in foreground are winning against frames in the background.
... int any

ListList of placeholder IDs that are accepted

  • No entry - accept all placeholders
  • Else - IDs of placeholders to be searched
The list can optionally be terminated with a 0 and up to two further numbers. Values after this 0 are interpreted as follows:
  • 0 : Do not calculate the coordinates of text placeholders
  • 1 : Calculate the coordinates of text placeholders (Default)
  • < 0 : Tolerance in points, since v4.2 R30820
    • sort=kSortRowwise : Placeholders with a top spacing ≤ |Tolerance| lie on one line
    • sort=kSortColwise : Placeholders with a left distance ≤ |Tolerance| lie in one column

Please note that placeholders that are full or partially in the overset, do not have (complete) XY coordinates. These placeholders are therefore not included in the result list when the coordinate calculation is activated.

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

All placeholders of the layer layer 1 of the current document

linklist::collect (lli, 0, "layer 1", kFirstIgnore);

All (also in overset!) placeholders of the layer layer 1 of the current document

linklist::collect (lli, 0, "layer 1", kFirstIgnore, kSortNo, 0, 0);

All placeholders with the IDs 400, 600 and 700 of the layer layer 1 of the current document page.

linklist::collect (lli, 0, "layer 1",
 	kFirstIgnore,
 	kSortNo,
 	400, 600, 700);

First placeholder with the ID ID 400, 600 or 700 of the inner top page corner of the layer layer 1 of the current document page

linklist::collect (lli, 0, "layer 1",
 	kFirstInnerTop,
 	kSortNo,// will be ignored
 	400, 600, 700);

Like previous example, but suppresss calculation of coordinates for text placeholder.Two 0s are expected, one for the end of placeholder list, one to suppress the calculation of the text coordinates.

linklist::collect (lli, 0, "layer 1",
 	kFirstInnerTop,
 	kSortNo,// will be ignored
 	400, 600, 700, 0, 0);

Version 1.2.2 (26 October 2005)
"--visible--" und "--active--" since Version 1.4 R310, 8. Feb. 2007
"--list--" since Version 1.4 R310, 17. Mar. 2007 Version 1.2.2 (26. Oktober 2005)
"--visible--" und "--active--" since Version 1.4 R310, 8. Feb. 2007
"--list--" since Version 1.4 R320, 17. Mar. 2007
kSortByZOrder since Version 2.1 R679, 22. April 2008

priint:comet InDesign® Plug-Ins, comet_pdf

link
linklist::text_collect
comet.link.collect

static int collect_any(
  LinkList lli,
  int page = 0,
  char* layer = "",
  int edge = 8,
  int sort = 0,
  ...)

Collect the placeholders of a given document area.

The function is equal to collect, except that frames do not have to be linked themselves to dive in and the calculation of coordinates of text placeholder is suppressed by default.

Name Type Default Description
Return int   0 or ErrorCode
lli LinkList - Valid LinkList with type = 0
page or frames int or itemlist 0 if (layer is not "--list--")
    document page (1-based)
    0 - current page

if (layer = "--list--")
    list of valid document frames

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

layer String or char* "" Limit search to the specified layer
"" : all layers
"--visible--" : visible layers only
"--active--" : active layer only
"--list--" : second parameter points to a list of document frames
edge int kFirstIgnore Find all placeholders or placeholder of a specified corner

kFirstIgnore - all placeholders
kFirstLeftTop
kFirstRightTop
kFirstOuterTop - left pages left upper corner, right pages right upper corner
kFirstInnerTop - left pages right upper corner, right pages left upper corner
kFirstLeftBottom
kFirstRightBottom
kFirstOuterBottom - left pages left bottom corner, right pages right bottom corner
kFirstInnerBottom - left pages right bottom corner, right pages left bottom corner
sort int kSortNo Sort the results list

kSortNo - Do not sort
kSortColwise - sorted according to left frame edge from top to bottom. In the image above there results

  blue
  red
  green
  orange

kSortRowwise - sorted from left to right by top of the frame. With the figure above, the following sort order results
  orange
  red
  green
  blue

kSortByZOrder - Frames in foreground are winning against frames in the background.
... int optional

ListList of placeholder IDs that are accepted

  • No entry - accept all placeholders
  • Else - IDs of placeholders to be searched
The list can optionally be terminated with a 0 and up to two further numbers. Values after this 0 are interpreted as follows:
  • 0 : Do not calculate the coordinates of text placeholders (Default)
  • 1 : Calculate the coordinates of text placeholders
  • < 0 : Tolerance in points, since v4.2 R30820
    • sort=kSortRowwise : Placeholders with a top spacing ≤ |Tolerance| lie on one line
    • sort=kSortColwise : Placeholders with a left distance ≤ |Tolerance| lie in one column

Please note that placeholders that are full or partially in the overset, do not have (complete) XY coordinates. These placeholders are therefore not included in the result list when the coordinate calculation is activated.

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

Collect all placeholders of a given frame and write some information to the log. Dont forget to clear the ItemList flist. The ItemRef added to this list was NOT allocated by the funtion query_links.

#include "internal/types.h"
#include "internal/text.h"
int query_links (ItemRef frameRef) { ItemList flist = itemlist::alloc (); LinkList lli = linklist::alloc (); ItemRef fr = item::alloc (); Link li; int inOverset = 0;
itemlist::append (flist, frameRef); linklist::collect_any (lli, flist, "--list--", kFirstIgnore, kSortNo); itemlist::clear (flist); // otherwise itemlist::release will delete frameRef too! wlog ("", "# %d Placeholders found.\n", linklist::length (lli));
li = linklist::first (lli); while (li) { if (!link::isframe (li)) { inOverset = textmodel::get_frame_containing (link::frame (li), link::pos (li), fr); if (!inOverset && link::length (li) > 0) { inOverset = textmodel::get_frame_containing (link::frame (li), link::pos (li)+link::length (li), fr); }
wlog ("", "# [%d, %d]", link::pos (li), link::pos (li)+link::length (li)); wlog ("", " %d (%d)", item::getint (link::frame (li)), item::getint (fr)); if (inOverset == -1) wlog ("", " in Overset"); wlog ("", "\n"); }
li = linklist::next (lli); }
linklist::release (lli);
return 0; }
int main () { query_links (gFrame); return 0; }

Version 1.3.4 (P/R 107)
"--visible--" and "--active--" since Version 1.4 R310, 8. Feb. 2007
"--list--" since Version 1.4 R320, 17. März 2007
kSortByZOrder since Version 2.1 R679, 22. April 2008

priint:comet InDesign® Plug-Ins, comet_pdf

link
collect
text_collect
comet.link.collect

static int text_collect(
  LinkList lli,
  ItemRef frameRef,
  int pos,
  int len,
  int cto,
  ...)

Collect all placeholder of a given text or a range of a given text

Name Type Default Description
Return int   0 or ErrorCode
lli LinkList - valid LinkList. After successful return, the list contains the links of the text (range) order by their positions. Table cells are ordered rowwise.
frameRef ItemRef 0 Textframe. If a text resides in more than one frame, all frames this are used to search.
0 : use current text
pos int 0 start here
len int kEnd length of text to be searched
cto int 0 (CheckTextCoordinates) Shall I calculate the text position in xy coordinates too (expensive!)
0 : do not calculate 1 : caculate xy coordinates of text
... int optional List of the placeholder IDs which are accepted
No entry - accept all placeholders
otherwise - only accept placeholders with the specified IDs

Examples : ..., 1, 2 : Only collect placeholders of ID1 and 2
#include "internal/types.h"
#include "internal/text.h"

Get the currently selected placeholder (by Martin Lucke).

#include "internal/types.h" 
#include "internal/text.h"
int main () { ItemRef txtframe = item::alloc (); LinkList lli = linklist::alloc (1); Link lk; int start, len, re;
textmodel::selection (&start, &len);
if(start >= 0) { re = textmodel::get_frame(start, txtframe); if (re >= 0) { linklist::text_collect(lli, txtframe, start, 1); if (linklist::length(lli)) { lk = linklist::first(lli); showmessage("Platzhalter gefunden!\n"); } else showerror("Sie haben keinen Platzhalter ausgewählt!"); } else showerror( serror (re)); } else showerror("Sie haben keinen Text ausgewählt!"); linklist::release(lli); item::release(txtframe);
return 0; }

Add a paragraph delimiter between two placeholders, if and only if both of them are not empty. Otherwise remove any exiting letters between these two placeholders. The script can be used as layout rule.

int main ()
{
    LinkList	lli 	= linklist::alloc ();
    String 		s1		= string::alloc ();	// content of first placeholder
    String 		inter	= string::alloc ();	// text between the two placeholders
    String 		s2		= string::alloc ();	// content of second placeholder
    int			i0; 	// start of placeholder 1
    int			i1; 	// end of placeholder 1
    int			i2; 	// start of placeholder 2
    int			i3; 	// end of placeholder 2
    Table 		T		= table::alloc ();
// collect placeholders linklist::text_collect (lli, gFrame, 0, frame::textlength (gFrame, 0)); if (linklist::length (lli) < 2) return 0;
// get the content of the first two placeholders string::set (s1, string::get_netweight (link::content (linklist::get (lli, 0)), 1, 1)); string::set (s2, string::get_netweight (link::content (linklist::get (lli, 1)), 1, 1));
// get the text between the two placeholders i0 = link::pos (linklist::get (lli, 0)); i1 = link::pos (linklist::get (lli, 0)) + link::length (linklist::get (lli, 0)); i2 = link::pos (linklist::get (lli, 1)); i3 = link::pos (linklist::get (lli, 1)) + link::length (linklist::get (lli, 1)); if (i2 > i1) frame::gettext (gFrame, inter, i1, i2-i1);
// set the text size table::get (T, gFrame, 0); if ( string::compare (s1, "<0x200B>") == 0   && string::compare (s2, "<0x200B>") == 0) { textmodel::set_fontsize (gFrame, i0, (i3-i0)+1, 0.2); if (table::is_valid (T)) table::space_before (T, 0.0); } else { textmodel::set_fontsize (gFrame, i0, (i3-i0)+1, 12.0); if (table::is_valid (T)) table::space_before (T, 4.0); }
// fix intermediate text if ( string::compare (s1, "<0x200B>") != 0   && string::compare (s2, "<0x200B>") != 0) { // both placeholder NOT empty, insert a paragraph if (string::compare (inter, "\r") != 0) { frame::replace (gFrame, "%!TT<ParaStyle:><ParaStyle:>", i1, i2-i1, 0); textmodel::clear_placeholders (i1, i2-i1, gFrame); } } else { // both placeholders empty, remove the paragraph if (i2 > i1) { frame::replace (gFrame, "", i1, i2-i1, 0); } }
return 0; }

Version 1.4.2, R 560, 9. Jan. 2007

priint:comet InDesign® Plug-Ins, comet_pdf

link
linklist::collect
collect_any
comet.CTextModel.collectLinks

static int sort(LinkList lli, sortfunc cmpFunc)

Sort a linklist.

The compare function cmpFunc must be defined in the script and must be of the following type:

   int yourCmpFunction (Link a, Link b)

The function is used by the sorter to check whether two list objects are well placed in the list. At calling time a stands before b. If you want to change the objects positions, return 1 otherwise 0.

Name Type Default Description
Return int   0 or ErrorCode
lli LinkList - Valid LinkList.
cmpFunc int yourCmpFunction (Link a, Link b) - Compare function.The function is used by the sorter to check whether two list objects are well placed in the list. At calling time a stands before b. If you want to change the objects positions, return 1 otherwise 0.

Do not use script global variables inside the function!
#include "internal/types.h"
#include "internal/text.h"

Collect all placeholders of the current page and sort them by different ways. Results are written to the log.

#include "internal/text.h"
#include "internal/types.h"
int w_lli (LinkList lli, char * trailer) { Link p; char pgs[100]; int i = 0;
wlog ("", "%s\n", trailer); while (i < linklist::length(lli)) { p = linklist::get (lli, i); wlog ("", "Pos %d, Seite %s [%d %d %d] : '%s'\n",   link::pos (p),   link::pagestr(p,pgs),   link::id(p),   link::id2(p),   link::id3(p),   link::content (p)); i++; } wlog ("", "\n"); }
int byName_asc (Link a, Link b) { char s1 [8000]; char s2 [8000];
strcpy (s1, link::content (a)); strcpy (s2, link::content (b));
if (strcmp (s1, s2) > 0) return 1;
else return 0; }
int byName_desc (Link a, Link b) { char s1 [8000]; char s2 [8000];
strcpy (s1, link::content (a)); strcpy (s2, link::content (b));
if (strcmp (s1, s2) < 0) return 1;
else return 0; }
int byPosition_asc (Link a, Link b) { if (link::pos (a) > link::pos (b)) return 1;
else return 0; }
int main () { LinkList lli = linklist::alloc (0);
linklist::collect(lli, page::get(gFrame), "", kFirstIgnore , 0, 0);
w_lli (lli, "Original");
linklist::sort (lli, byName_asc); w_lli (lli, "By name (ascent)");
linklist::sort (lli, byName_desc); w_lli (lli, "By name (descent)");
linklist::sort (lli, byPosition_asc); w_lli (lli, "By position (ascent)");
return 0; }

Version 3.2.1 R2321, 3.3.2011

priint:comet InDesign® Plug-Ins, comet_pdf

static int insert_toc_entry(
  LinkList placeholderList,
  int designate = kDesignateDocument,
  char* publication = 0,
  char* documentId = 0,
  char* xmlpath = 0,
  int flags = 0)

Collect data for a table of content.

The function collects all data nessacary for a table of content (TOC). If you are currently connected to a PublishingServer, the collected data are sent to server automatically. To use the TOC data use the Java-Server-Plugin CometTableOfContents which provides special DataQuery-methods, which can be used in Data Providers and in text placeholders of the entity Table Of Contents in a document. TOC entries which already exist with the same placeholder and scope are automatically deleted.

The function does NOT create a list of content inside the document. It only collects the DATA for a possible table of content!

Name Type Default Description
Return int   0 oder ErrorCode
placeholderList LinkList - List of placeholder IDs which are taken into consideration when creating the entries.
empty list = all placeholders
The list has to be allocated with linklist::alloc(1);
designate int - Scope. The following values are supported:

kDesignateDocument
kDesignateVisibleLayers
kDesignateActiveLayer
publication String or char* "" Name / ID of the publication.
Default is the value of the XML-attribute <publication> of the document Root element. Only used for output.
documentId String or char* "" ID of the document.
Default is the value of the XML-attribute <documentId> of the document Root element. Only used for output.
xmlpath String or char* "" Save data to an XML file. Already existing XML files are overwritten.

 Connected to PubServer
"" : Don't write an additional XML file
else : Complete path to output file.

 Without PubServer connection
"" : Put XML next to the InDesign® document. When the document is not yet saved, the file is written to the documents folder.
else : Complete path to the output file.
flags int 0 Additional specifications. Add the following values:

1 : Add inlines to the results too
2 : Sort results by page, XY position, text position
8 : Add hidden frames to the results too ('Hidden' means the frame has been set to 'Invisible, Hidden , Visibility : No' (or whatever you call it). It does not mean that the frame is invisible because the layer, color, transparency, position (overset, paste board) or similar make the frame invisible!)
#include "internal/types.h"
#include "internal/text.h"

Create TOC entries for the entire document

#include "internal/types.h"
int main () { LinkList placeholders = linklist::alloc(1); int result = linklist::insert_toc_entry(placeholders, kDesignateDocument, "myPublication", "12345");
linklist::release(placeholders); return result; }

Create TOC entries for a certain placeholder

#include "internal/types.h"
int main () { LinkList placeholders = linklist::alloc(1); int result;
linklist::insert(placeholders, 67301234);
// use publication and documentId from document XML attributes result = linklist::insert_toc_entry(placeholders, kDesignateDocument);
linklist::release(placeholders); return result; }

Version 4.0 R5804, 23. Sep 2014 Parameter xmlpath since v4.0.4, R8450, 16. Jul 2015
Parameter flags since v4.1, R21700, 2. Feb 2018

Available:
Comet-Plug-Ins, comet_pdf

comet.link.insertTocEntry

static int delete_toc_entry(
  LinkList placeholderList,
  int designate = kDesignateDocument,
  char* publication = 0,
  char* documentId = 0)

Delete previously created table of content entries

The function deletes previously created table of content entries of certain or all placeholders of a certain scope.

Name Type Default Description
Return int   0 oder ErrorCode
placeholderList LinkList - List of placeholder IDs to delete empty list = all placeholders
The list has to be allocated with linklist::alloc(1);
designate int - Scope. The following values are supported:
kDesignateDocument, kDesignateVisibleLayers and kDesignateActiveLayer
publication String or char* "" Name / ID of the publication.
Default is the value of the XML-attribute <publication> of the document Root element. Only used for output.
documentId String or char* "" ID of the document.
Default is the value of the XML-attribute <documentId> of the document Root element. Only used for output.

Version 4.1.6 R26027

Available:
Comet-Plug-Ins, comet_pdf

comet.link.deleteTocEntry

Building a list. The list will then run through three times. During the first run all elements are written. Then it will be written from the position of the element <1, 3, 6, 9>. Before the third run all elements <1, 11, 22, 33> will be deleted

int main ()
{
    int			i	= 0;
    LinkList	lli	= linklist::alloc (2);	//  List of product (record) ids
    Link		lk;
// Fill list for (i=1; i<6; i++) linklist::insert (lli, 1, i, i*2, i*3); linklist::insert (lli, 1, 11, 22, 33, 1); linklist::insert (lli, 1, 11, 22, 33, 4);
// Write all elements i = 0; for (  lk = linklist::first (lli);   lk != 0;   lk = linklist::next (lli)) { showmessage ("1. Liste %d. Element : %d <%d, %d, %d>",   ++i,   link::classid (lk),   link::id (lk),   link::id2 (lk),   link::id3 (lk)); }
// Set list start at the element <1, 3, 6, 9> linklist::set_pos (lli, linklist::find (lli, 1, 3, 6, 9)); i = 0; for (  lk = linklist::current (lli);   lk != 0;   lk = linklist::next (lli)) { showmessage ("2. Liste %d. Element : %d <%d, %d, %d>",   ++i,   link::classid (lk),   link::id (lk),   link::id2 (lk),   link::id3 (lk)); }
// Delete the element <1, 11, 22, 33> from the list linklist::remove (lli, 1, 11, 22, 33);i = 0; for (  lk = linklist::first (lli);   lk != 0;   lk = linklist::next (lli)) { showmessage ("3. Liste %d. Element : %d <%d, %d, %d>",   ++i,   link::classid (lk),   link::id (lk),   link::id2 (lk),   link::id3 (lk)); }
linklist::release (lli); return 0; }

Update all type names, family names, names and species identification code in the document.

int main ()
{
    int			i	= 0;
    LinkList	lli	= linklist::alloc (1);	// Placeholder list
    Link		lk;
// Fill list linklist::insert (lli, 1); // Type name linklist::insert (lli, 3); // Family name linklist::insert (lli, 4); // Name linklist::insert (lli, 6); // Species identification code
linklist::load (lli);
linklist::release (lli); return 0; }

Ascertain the placeholder data of all type names, family names, names and species identification code in the document.

int main ()
{
    int			i	= 0;
    LinkList	lli	= linklist::alloc (1);	// Placeholder list
    LinkList	rets	= linklist::alloc (0);	// User-defined list
    Link		lk;
    String		content = string::alloc ();
    char		page[256];
// Fill list linklist::insert (lli, 1); linklist::insert (lli, 3); linklist::insert (lli, 4); linklist::insert (lli, 6); linklist::insert (lli, 12); linklist::insert (lli, 44444);
linklist::sync (lli, rets, 0); for (  lk = linklist::first (rets);   lk;   lk = linklist::next (rets)) { char m[500];
strcpy (m, "Placeholder %d <%d, %d, %d>"); strcat(m, "\n Contents : %s"); strcat(m, "\n Status : %d"); strcat(m, "\n Page : %d (%s)"); strcat(m, "\n Position : %d-%d"); strcat(m, "\n Text length : %d");
showmessage (m,   link::placeholderid (lk),   link::id (lk),   link::id2 (lk),   link::id3 (lk),   link::gettext (lk, content),   link::sync (lk),   link::pagenum (lk),   link::pagestr (lk, page),   link::pos (lk)+link::length (lk)   link::textlen (lk)); } linklist::release (rets);
// Placeholder not found for (  lk = linklist::first (lli);   lk;   lk = linklist::next (lli)) { if (link::sync (lk) < 0) { showmessage ("Placeholder %d not found",   link::placeholderid (lk)); } }
linklist::release (lli); string::release (content); return 0; }

Since
1.0.19
See Also
Link
link::id
link::sid

Alphabetic index HTML hierarchy of classes or Java