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. |
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. |
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 |
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 |
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 |
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:
|
position | int | -1 | Insert position. The new element will be inserted before the specified position.
List positions are counted beginning with 0. -1 : Append |
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 |
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 |
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 |
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. |
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 |
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; }
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. |
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 |
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 |
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 |
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 |
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 |
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. |
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. | |||
linklist::load (lli) linklist::load (lli, kDesignateVisibleLayers) |
|||
designate | int | kDesignateDocument | Which part of the document is to be processed? kDesignateCursor kDesignateSelected kDesignateDocument kDesignateVisibleLayers kDesignateActiveLayer |
linklist::load (lli, 0, gItemRef) |
|||
designate | int | - | unused |
itemRef | ItemRef | - | Only process these frame. |
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 |
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. | |||
linklist::load (lli) linklist::load (lli, kDesignateVisibleLayers) |
|||
designate | int | kDesignateDocument | Which part of the document is to be processed? kDesignateCursor kDesignateSelected kDesignateDocument kDesignateVisibleLayers kDesignateActiveLayer |
linklist::load (lli, 0, gItemRef) |
|||
designate | int | - | unused |
itemRef | ItemRef | - | Only process these frames. |
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 |
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 kDesignateActiveLayer |
itemRef | ItemRef | 0 | Only process these frame. |
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. | |||
linklist::load (lli) linklist::load (lli, kDesignateVisibleLayers) |
|||
designate | int | kDesignateDocument | Which part of the document is to be processed? kDesignateCursor kDesignateSelected kDesignateDocument kDesignateVisibleLayers kDesignateActiveLayer |
linklist::load (lli, 0, gItemRef) |
|||
designate | int | - | unused |
itemRef | ItemRef | - | Only process these frames. |
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 |
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 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
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. |
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 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
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. |
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 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 |
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! |
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 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!) |
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; }
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. |
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; }
Alphabetic index HTML hierarchy of classes or Java