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 type = 0)
Create a new empty list of links (Placeholders). The list must be deleted again with linklist::release. With the definition of the list a specification can be made whether the list contains placeholderIDs or record IDs. This determination is required if the functions load, store or sync are to be executed.
Name | Type | Default | Description |
Return | LinkList | Empty list. The list must be
deleted again using linklist::release. 0 in the case of error |
|
type | int | 0 | List type 0 : simple list (for instance for collect and collect_any). Any list entries will be ingored with load, store, sync and apply. 1 : The list contains IDs of placeholders. The list must contain at least one object in order to be able to be used with load, store, sync or apply. The objects must be inserted using linklist::insert (lli, plID). 2 : The list contain object IDs. The list must contain at least one object in order to be able to be used with load, store, sync or apply. The objects must be inserted using linklist::insert (lli, plID, ID1, ID2, ID3). |
static int release(LinkList lli)
Delete the list and all its elements which was set up using linklist::alloc. The contents of list elements (Datatype Link), which are still used in the script are invalid thereafter. Empty lists must also be deleted.
Name | Type | Default | Description |
Return | int | 0 or ErrorCode | |
lli | LinkList | - | List to be deleted. The list and all its elements will be deleted. The contents of list elements (Datatype Link), which are still used in the script are invalid thereafter. |
static int clear(LinkList lli)
Delete all the entries to a list. The call is particularly useful for the results list, because these list can occupy a great deal of memory. The list continues to exist after the call. If you wish to delete the entire list, use release.
Name | Type | Default | Description |
Return | int | 0 or ErrorCode | |
lli | LinkList | - | valid LinkList with the placeholders in the document that are to be checked. |
static int type(LinkList lli)
List type, as specified when it was created.
Type | Description |
1 | placeholder list. The list contains IDs of placeholders and can be used in the load, store and sync methods. |
2 | List with class - and oject IDs. The list contains IDs of objects each with a class number can be used in the load, store and sync methods. |
otherwise | User-defined list indefinite types. The list cannot be used in the load, store and sync functions. |
Name | Type | Default | Description |
Return | int | Type of list 1 Placeholder IDs 2 Class numbers with object IDs otherwise user-defined list |
|
lli | LinkList | - | valid LinkList |
static int length(LinkList lli)
Number of elements of the list.
Name | Type | Default | Description |
Return | int | Number of the list elements or 0 | |
lli | LinkList | - | Valid LinkList or 0 |
int insert_placeholder(
LinkList lli,
int placeholderId,
KeyValues keyValues,
int actionType,
int pos)
Insert a new placeholder in a list. Only valid for placeholder lists or untyped lists.
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 |
plID | int | - | ID of a placeholder |
keyValues | KeyValues | 0 | List 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 object will be inserted before the specified position.
List positions are counted beginning with 0. -1 Attach |
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 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 |
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 object will be inserted before the specified position.
List positions are counted beginning with 0. -1 Attach |
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 object will be inserted before the specified position.
List positions are counted beginning with 0. -1 Attach |
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 Attach |
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 object will be inserted before the specified position.
List positions are counted beginning with 0. -1 Attach |
⇨ 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 Attach |
static Link get(LinkList lli, int position)
Get the object of the list. The object contained there must not ever be deleted using link::release.
Name | Type | Default | Description |
Return | Link | Object 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 object with the specified values? The (0-based) position of the first object found will be returned. The parameter of the function must match the list type, placeholder lists have one number, object 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); // 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);
// 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, next, previous (prev), last or 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 |
Fill a list an run once forwards.
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 the list will run once from that point.
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 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)
Execute the load action for all elements in the list. The effect of the function is as if the specified elements in the panel of the class number (object lists) or in the placeholder panel (placeholder lists) were eyed and then the panel command 'load the marked entries' is executed. If there are several placeholders in the document with the same definitions, then all placeholder will be processed.
Object lists (linklist::alloc (2)) repsectively expect a \URL[Class number]{../InDesign/Plugins/w2plugins.html#ClassID and the three object IDs. In this version however only the class ID of the first list entry will be evaluated. It will be assumed that all other objects belong to the same class.}
Name | Type | Default | Description |
Return | int | 0 or ErrorCode | |
lli | LinkList | - | Valid LinkList with type = 1 or 2. With list of type 0 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 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)
Execute the write action for all elements of the list. The functions operates as if the specified elements in the panel of the class number (object lists) or in the placeholder panel (placeholder lists) are eyed and then the panel menu command 'load the marked entries' is executed. If there are several placeholders in the document which have the same definition, all placeholders will be processed. Object lists (linklist::alloc (2)) each expect a Class number and the three object IDs. In this version however only the class ID of the first list entry will be evaluated. It will be assumed of all other objects that they belong to the same class.
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)
Ascertain the current value of placeholders in the document. Before the data can be processed, the
sync action can be executed for all elements in the entry list.
If the function has been successfully executed, the results list results receives all information about
all placeholders found in the document, for more see the methods of the class link. The results list must be initialised using alloc
and cleared before the execution.
Following the end of the function, the entry list lli can be used to determine if a list element
does not have a placeholder in the document : If the link::sync of an element of this list < 0, there is no placeholder
in the document which corresponds to the conditions of this entry.
Name | Type | Default | Description |
Return | int | 0 or ErrorCode | |
lli | LinkList | - | Valid LinkList with the placeholders to the checked in the document. With list of type 0 all possible list entries are ignored and for all placeholders the target frames/text processed. |
results | LinkList | - | Results list. The results list must be initialised using alloc and cleared before the execution. |
doExec | int | 0 | 0 Ascertain the current status the placeholder without
prior checking 1 Before ascertaining the states the checking (Sync script of the placeholder) is carried out |
⇨ 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 specific action for all the elements in the list. The action is stored as script or SQL instruction in the database table iQuest.actions. Object lists (linklist::alloc (2)) each expect a \URL[class number]{../InDesign/Plugins/w2plugins.html#ClassID and the three object IDs. In this version however only the class ID of the first list entry will be evaluated. It will be assumed that all other objects belong to the same class.}
Name | Type | Default | Description |
Return | int | 0 or ErrorCode | |
lli | LinkList | - | Valid LinkList with type = 1 or 2. With lists of type 0 all possible list entries are ignored and for all placeholders the target frames/text 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,
...)
Search placeholders on given pages or given layers. Placegolders are identified by their placeholder ID and assumed to be linked
with an objekt. 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 |
List 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,
...)
Search for placeholders on a page or page layer or on a given list of frames. Frames do not have to be linked with a placeholder.
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 |
List 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 Paltzhalter 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); // 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)); }
// 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