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 listintent int 0 Intention (Type) of the list. See here for more information. - Since
- Processing of all placeholders for load, store, sync and apply with type = 0 is implemented from version 1.1.6.
- See Also
- 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.
- Since
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- 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 - Since
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- 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 : Productslli LinkList - Valid LinkList - Since
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- 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 - Since
- Available
- 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- Preconditions
- #include "internal/types.h"
- Since
- 4.1 R21475
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- alloc
get
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; }
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- Since
- 4.1 R21475
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- 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 : Appendsid 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- Deprecated
- please use linklist::insert_placeholder or linklist::insert_id instead
- Since
- Parameter sid from Version 1.3 (Build 96)
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- 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- Deprecated
- please use linklist::insert_placeholder or linklist::insert_id instead
- Since
- Version 1.3 (Build 96)
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- 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. - Since
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- 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 - Since
- Parameter sid since Version 1.3 (Build 96)
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- 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; }- Since
- Parameter sid since Version 1.3 (Build 96)
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- 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. - Since
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- 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 - Preconditions
- 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.
- Postconditions
- The current list position will be changed correspondingly.
- Since
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- set_pos
next
prev
last
current
next
prev
last
current
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;
}
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 - Preconditions
- 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.
- Postconditions
- The current list position will be changed correspondingly.
- Since
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- 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 - Preconditions
- 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.
- Postconditions
- The current list position will be changed correspondingly.
- Since
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- 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 - Preconditions
- 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.
- Postconditions
- The current list position will be changed correspondingly.
- Since
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- 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 - Preconditions
- 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.
- Postconditions
- The current list position will be changed correspondingly.
- Since
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- 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. - Postconditions
- The current position is changed correspondingly.
- Since
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- next
prev
first
last
current
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));
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
kDesignateActiveLayer2. 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 enditemRef ItemRef - 0 : process current text
otherwise process the text of this frame- Preconditions
- #include "internal/types.h"
#include "internal/text.h" - Since
- 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; } - Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- type
alloc
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);
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
kDesignateActiveLayer2. 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 enditemRef ItemRef - 0 : process current text
otherwise process the text of this frame- Preconditions
- #include "internal/types.h"
#include "internal/text.h" - Since
- 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 - Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- type
load
alloc
see the examples for load
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
kDesignateActiveLayeritemRef ItemRef 0 Only process these frame. - Preconditions
- #include "internal/types.h"
#include "internal/text.h" - Postconditions
- 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.
- Since
- 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 - Available
- priint:comet InDesign® Plug-Ins
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;
}
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
kDesignateActiveLayer2. 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 enditemRef ItemRef - 0 : process current text
otherwise process the text of this frame- Preconditions
- #include "internal/types.h"
#include "internal/text.h" - Since
- 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 - Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- type
alloc
Analgous to the examples for load
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 framesedge 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 cornersort 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
- 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.
- Preconditions
- #include "internal/types.h"
#include "internal/text.h" - Since
- 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 - Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- link
linklist::text_collect
comet.link.collect
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);
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 framesedge 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 cornersort 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
- 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.
- Preconditions
- #include "internal/types.h"
#include "internal/text.h" - Since
- 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 - Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- link
collect
text_collectcomet.link.collect
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; }
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 textpos 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- Preconditions
- #include "internal/types.h"
#include "internal/text.h" - Since
- Version 1.4.2, R 560, 9. Jan. 2007
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- link
linklist::collect
collect_anycomet.CTextModel.collectLinks
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;
}
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!- Preconditions
- #include "internal/types.h"
#include "internal/text.h" - Since
- Version 3.2.1 R2321, 3.3.2011
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf
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; }
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
kDesignateActiveLayerpublication String or char* "" Name / ID of the publication. This information is only used for the output.
0 or "" : Value of the XML attribute publication of the root element of the XML structure of the documentdocumentId String or char* "" ID of the document. This information is only used for the output.
0 or "" : Value of the XML attribute documentId of the root element of the XML structure of the documentxmlpath 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!)- Preconditions
- #include "internal/types.h"
#include "internal/text.h" - Since
- 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 - Comet-Plug-Ins, comet_pdf
- See Also
- comet.link.insertTocEntry
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; }
Available:
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 kDesignateActiveLayerpublication 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.- Since
- Version 4.1.6 R26027
- Comet-Plug-Ins, comet_pdf
- See Also
- comet.link.deleteTocEntry
Available: