String lists.

Here you will find examples to use stringlist.

String lists. The lists can be filled either 'manually' or with the StringIDs of the list panel (e.g. the Product Pool).

static StringList alloc(int classid, int selection_type = 0)

Get the string IDs of the panels which contain the objects of the desired classid. If no corresponding panel is found, 0 is returned. Other the list will be filled with the desired StringIDs of the loaded objects. The result list must again be deleted using stringlist::release.

Please note that there is a big difference between StringLists allocated with a ClassID and StringLists allocated without a class id (or classID = 0):

Lists with a class id are reflecting the appropriate panel. Normally they doesn't contain own objects, but requesting the panel according to their class id for object information. You can use this lists to query object information, see here. But the elements of this lists are static, either all or all eye-marked panel entries.

Lists without a class id are more felxible with their members. They contain own objects. You can fill the lists with any strings you want or use it as to be a function parameter. A call to datapool::get_products for instance fills the list with the string ids of the found products. But, on the other hand, you can not use this lists to query more information like the product name or something (For full flexibility on products, use productlist and its calls.)

Name	Type	Default	Description
Return	StringList		Created list of the 0
classid	int	-	Class ID of the panel
selection_type	int	kAll	kAll : All datasets of the panel kEyeMarked : Only the eye marked datasets of the panel kSelected : Selected panel entries only

Preconditions

#include "internal/panels.h"

Create a list with the string IDs of the marked products.

#include "internal/panels.h"

StringList 		li = stringlist::alloc (kPanelProducts, kEyeMarked);

char		*	str;

for (str = stringlist::first (li); str; str = stringlist::next (li))
{
    showmessage (str);
}

stringlist::release (li);

Since

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

static StringList alloc()

Create a new empty list. The list must again be deleted using stringlist::release.The list must again be deleted using stringlist::release

Please note that there is a big difference between StringLists allocated with a ClassID and StringLists allocated without a class id (or classID = 0):

Lists with a class id are reflecting the appropriate panel. Normally they doesn't contain own objects, but requesting the panel according to their class id for object information. You can use this lists to query object information, see here. But the elements of this lists are static, either all or all eye-marked panel entries.

Lists without a class id are more felxible with their members. They contain own objects. You can fill the lists with any strings you want or use it as to be a function parameter. A call to datapool::get_products for instance fills the list with the string ids of the found products. But, on the other hand, you can not use this lists to query more information like the product name or something (For full flexibility on products, use productlist and its calls.)

Name	Type	Default	Description
Return	StringList		Erzeugte Liste oder 0

Create a new empty list.

StringList = stringlist::alloc ();
 	stringlist::release (li);

Since

Available

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

static int release(StringList li)

Delete a list created with stringlist::alloc.

Name	Type	Default	Description
li	StringList	-	List to be deleted

Since

Available

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

static int length(StringList li)

Ascertain the number of elements of a list.

Name	Type	Default	Description
Return	int		Number of entries in the list
li	StringList	-	List

int len = stringlist::length (li);

Since

Available

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

static char* first(StringList li)

Get the first entry of a non-empty StringList. After successful execution, the current list pointer is at the top of the list.

The return value is the char* content of the list entry found. The return value must not be changed or released! Please also note that the list may contain empty strings that return the value 0!

Name	Type	Default	Description
Return	char*		First value of the list as char* The return value must not be changed or released!
li	StringList	-	List with at least one element

Postconditions

The current list pointer is now at the beginning of the list.

The following example can be used for list that have no 0 records.

int main ()
{
    StringList		li	= stringlist::alloc ();
    int				i;
    char		*	s;

    for (i=1; i<6; i++) stringlist::insert (li, itoa (i));
    for (s=stringlist::first (li); s; s=stringlist::next (li))
    {
        showmessage ("%s", s);
    }
    stringlist::release (li);
}

Since

Available

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

See Also

next
prev
last
get
get_pos

static char* next(StringList li)

Get the successor of the current entry of a StringList. Before the call, the current list pointer must have been set with a suitable function (first, get_pos, get, ...)! After successful execution, the current list pointer is moved forward one position.

The return value is the char* content of the list entry found. The return value must not be changed or released! Please also note that the list may contain empty strings that return the value 0!

Name	Type	Default	Description
Return	char*		Successor of the current entry as char* The return value must not be changed or released!
li	StringList	-	StringList list with defined list position (first, get_pos, get, ...)

Preconditions

Current list pointer is set (e.g. with first, get_pos, get, ...)

Postconditions

Current list pointer is relocated one position onwards

Since

Available

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

See Also

first
prev
last
get
get_pos

static char* prev(StringList li)

Get the predecessor of the current entry of a StringList. After successful execution, the current list pointer is moved backward to the beginning of the list by one position.

The return value is the char* content of the list entry found. The return value must not be changed or released! Please also note that the list may contain empty strings that return the value 0!

Name	Type	Default	Description
Return	char*		Predecessor of the current entry as char* The return value must not be changed or released!
li	StringList	-	StringList with defined list position (last, get_pos, get, ...)

Preconditions

Current list pointer is set (e.g. with last, get_pos, get, ...)

Postconditions

Current list pointer is relocated one position backwards

Since

Available

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

See Also

first
next
last
get
get_pos

static char* last(StringList li)

Get the last entry of a non-empty StringList. After execution, the current list pointer is at the last element of the list.

The return value is the char* content of the list entry found. The return value must not be changed or released! Please also note that the list may contain empty strings that return the value 0!

Name	Type	Default	Description
Return	char*		Last value of the list as char* The return value must not be changed or released!
li	StringList	-	List with at least one element

Postconditions

The current list pointer is now at the end of the list.

Since

Available

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

See Also

first
next
prev
get
get_pos

static int get_pos(
  StringList li,
  char* val,
  int setPos = 0)

Search for the position of a value in the list. If the value is not found, the function returns -1. List positions are 0-based - so the first element has the position 0, the final element the position length-1.

Name	Type	Default	Description
Return	int		>= 0 : First occurrence of a value in the list -1 : Value not found
li	StringList	-	List in which the value is to be search for
val	String or char*	-	The value to search for
setPos	int	0	0 : Leave list positions unchanged 1 : Set current list position to the found index Not available in Illustrator.

Postconditions

If the value was found in the list and setPos is > 0, the current list position is set to the found index.

Since

Available

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

See Also

get

static char* get(
  StringList li,
  int pos,
  int doSelect= 0)

Get the i-th element of the list. List positions are 0-based, the first element has the position 0, the final the position length-1.

Name	Type	Default	Description
Return	char*		Value of the list at the position i or 0. The return value is read only, do NOT CHANGE. The result will be overridden on following calls to the function. See here to learn more about functions returning r/o char* values.
li	StringList	-	List from which the element is to be fetched
pos	int	-	0-based list position
setPos	int	0	0 : Leave list positions unchanged 1 : Set current list position to pos Not available in Illustrator.

Postconditions

If setPos > 0, the current list position is located at i.

char * str	= stringlist::get (li, 0);

wlog ("", "%s\n", stringlist::get (li, 0));

char * str;

:
str = stringlist::get (li, 10, 1);

Since

Available

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

See Also

get_pos

static int append(StringList li, char* val)

Append element to the list. At the end of the list, a new string object is created, into which the content of the passed string val is duplicated.

Name	Type	Default	Description
Return	int		1 action successful, otherwise 0
li	StringList	-	List to append to
val	String or char*	-	Value to be appended

stringlist::append (li, k);

Since

Available

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

See Also

insert
remove
remove_pos
clear

static int insert(
  StringList li,
  char* val,
  int pos = -1)

Insert element into the list. At the given position, a new string object is created, into which the content of the passed string val is duplicated. List positions are 0-based, the first element has the position 0, the final the position length-1.

Name	Type	Default	Description
Return	int		1 action successful, otherwise 0
li	StringList	-	List to which the insert is to be made
val	String or char*	-	Value to be inserted
pos	int	-	Point of insert 0 : List start Value < 0 or >= length : Append otherwise : Error

stringlist::insert (li, 3, 0);

Since

Available

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

See Also

append
remove
remove_pos
clear

static int remove(StringList li, char* val)

Remove first occurence of a value from a list.

Name	Type	Default	Description
Return	int		1 : Action successful 0 : otherwise
li	StringList	-	List to remove from
val	String or char*	-	Value which is to be removed from the list

Since

Available

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

See Also

append
insert
remove_pos
clear

static int remove_pos(StringList li, int pos)

Remove a position from the list. List positions are 0-based, the first element has the position 0, the final the position length-1.

Name	Type	Default	Description
Return	int		1 : Action successful 0 : otherwise
li	StringList	-	List
pos	int	-	0-based delete position

Since

Available

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

See Also

append
insert
remove
clear

static int clear(StringList li)

Remove all elements of the list

Name	Type	Default	Description
Return	int		1 : Action successful 0 : otherwise
li	StringList	-	List

stringlist::clear (li);

Since

Available

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

See Also

append
insert
remove
remove_pos

static int reload(long classid, int reloadAll = 0)

Reload the data records of a panel list. To reload the complete list, set reloadAll to 1. If you want only to update the linkbuttons of the list(s), you can use the command placeholder::update_link_states.

Name	Type	Default	Description
Return	int		0 or ErrorCode
classid	int	-	Palette number specified by Werk II 0 - update all open panels
reloadAll	int	0	Reload complete list? 0 : No, only reload list entries 1 : Yes, reload the complete list

Since

Parameter reloadAll neu seit Version 2.1 R 684, 25 April 2008

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

placeholder::update_link_states
list::reload

static int classid(StringList li)

ClassID of the list records. The list will be initialised with this class (stringlist::alloc).

Name	Type	Default	Description
Return	int		0 or ClassID.
li	StringList	-	List the class ID of which is to be ascertained

Since

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

static int complete(StringList li)

Does the list contain all IDs of the panel or only the eye-marked records?

Name	Type	Default	Description
Return	int		0 : Only selected records 1 : all records of the panel
li	StringList	-	Liste

Since

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

static char* gettext(
  StringList li,
  long index,
  char* attribute,
  char* result)

Get the value of an element of a list element. The requestable attribute are dependent on the class ID of the list. The table of valid value can be found here.

If the list was created as to be a panel list (alloc with ClassID) only its class id, selection type and length are used. The results are taken from panel directly, not from the current list content.

If the list was created as to be a common list, the given attribute is ignored and the result is taken from the list.

Name	Type	Default	Description
Return	String or char* (Depends on parameter result)		Attribut value or empty. The result is a pointer to result. When the datatype of result is char*, the pointer must have sufficient allocated memory (char[100], alloc (100)).
li	StringList	-	List
index	int	-	0-based memory
attribute	String or char*	-	Which value you want to retrieve? See here. Ignored for lists without a class id. In this case the string at the given index is returned only.
result	String or char*	-	Reserved memory for the result.

Since

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

static int getint(
  StringList li,
  long index,
  char* attribute)

Get the value of a list element as an integer. The queryable attributes are dependent on the class ID of the list. If the attribute contains a text value the result of the call is undefined.

If the list was created as to be a panel list (alloc with ClassID) only its class id, selection type and length are used. The results are taken from panel directly, not from the current list content.

If the list was created as to be a common list, the given attribute is ignored and the result is taken from the list.

Name	Type	Default	Description
Return	int		Attribute value
li	StringList	-	List
index	int	-	0-based list index
attribute	String or char*	-	Which value you want to retrieve? See here. Ignored for lists without a class id. In this case the string as integer (if possible) at the given index is returned only.

Since

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

static float getfloat(
  StringList li,
  long index,
  char* attribute)

Get the value of a list element as a decimal. The queryable attributes are dependent on the class ID of the list. If the attribute contains a text value the result of the call is undefined.

If the list was created as to be a panel list (alloc with ClassID) only its class id, selection type and length are used. The results are taken from panel directly, not from the current list content.

If the list was created as to be a common list, the given attribute is ignored and the result is taken from the list.

Name	Type	Default	Description
Return	int		Attribute value
li	StringList	-	List
index	int	-	0-based list index
attribute	String or char*	-	Which value you want to retrieve? See here. Ignored for lists without a class id. In this case the string as float (if possible) at the given index is returned only.

Since

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

int sort(
  StringList li,
  int direction = 0,
  int case_insensitive = 0,
  char* collation = "")

Sort the list. Attention : Lists, allocated with a non empty class id (for example stringlist::alloc (3, 2)) only containing virtual entries and unable to sort. To sort such lists, you have to copy each value to another list before (see example).

Name	Type	Default	Description
Return	int		0 or ErrorCode
li	StringList	-	list to sort
direction	int	0	sort oder 0 : ascent 2 : descent
case_insensitive	int	0	Sort case insensitive or not? 0 : Case sensitive (ABC..abc) 1 : Case insensitive (aAbBcC...)
collation	String or char*	""	Valid collation ID. On the Mac, you will get a list of available collations by typing locale -a in the terminal application. Here are some examples: en_US.ISO8859-1 de_DE.ISO8859-1 sv_SE.ISO8859-1 tr_TR.ISO8859-9

Sort the currently selected products. The real values are collected in a temporarily list before.

int wstring (char * s)
{
    if (s)
    {
        wlog ("", "    '%s'\n", s);
    }

    return 0;

}
int main ()
{
    StringList		li1	= stringlist::alloc (3, 2);	// Selektierte Produkte
    StringList		li	= stringlist::alloc ();		// Namen der selektierten Produkte
    char		*	s;
    char			str [800];
    int				i;

    for (i = 0; i < stringlist::length (li1); i++)
    {
        stringlist::gettext (li1, i, "Num", str);
        wlog ("", "%d***%s'\n", i, str);
        stringlist::append (li, str);
    }

    wlog ("", "unsoerted\n");
    for (s = stringlist::first (li); s; s = stringlist::next (li)) wstring (s);

    stringlist::sort (li, 0);
    wlog ("", "sorted\n");
    for (s = stringlist::first (li); s; s = stringlist::next (li)) wstring (s);

    stringlist::sort (li, 1);
    wlog ("", "sorted descent\n");
    for (s = stringlist::first (li); s; s = stringlist::next (li)) wstring (s);

    return 0;
}

Since

Version 2.1, R 1580, 1. Okt. 2009

Available

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

case_insensitive and collation since v3.4 R7000, 13. Nov. 2014

See Also

idtypelist::sort

static char* to_xml(StringList list, char* rootElementName = "strings")

Generate a XML structure of a StringList object.If you think about using this function, you might be interested in further information about cscript / java interaction. Related information can be found here.

Name	Type	Default	Description
Return	char *		xml string or 0 on errors. The result string is valid until the next time a to_xml function is called and must not be changed or released.
list	StringList	-	object
rootElementName	String or char*	strings	name of the root element

Since

4.0.5 R9650

See Also

comet.publication.toXMLStringList

static StringList from_xml(char* xml)

Create a StringList object from a xml structure.

If you think about using this function, you might be interested in further information about cscript / java interaction. Related information can be found here.

Name	Type	Default	Description
Return	StringList		Object of type StringList. This list must be released using stringlist::release.
xml	String or char*	-	xml structure

Since

4.0.5 R9650

See Also

comet.publication.fromXMLStringList

static int add_all(
  StringList target,
  StringList src,
  int deleteFromSource)

Append all elements from list src to list target. If deleteFromSource is non-zero, all elements are removed from source list. (but not deleted)

Name	Type	Default	Description
Return	int		0 oder Fehlercode.
target	StringList	-	target list
src	StringList	-	source list
deleteFromSource	int	0	delete elements from source

Since

4.0.5 R9700

You can find examples on string lists in the documentation of list. The examples shown there can be used analogously for lists of the type string list.

Create a list with the string IDs of the marked products.

StringList 	li = stringlist::alloc (3, 1);

char	*	str;

for (str = stringlist::first (li); str; str = stringlist::next (li))
{
    showmessage (str);
}

stringlist::release (li);

The third example demonstrates the differences between class-id based stringlists and string lists without any class id allocated. Mark some entries of the product panel with an eye, and select some other entries of the list by hiliting.

int main ()
{
    int 			id1, id2, id3;
    int 			num		= 0;
    List 			prod  	= list::alloc();
    List 			prod2 	= list::alloc();
    List 			prod3 	= list::alloc();
    StringList 		prod4 	= stringlist::alloc ();	// StringList without Class-ID
    StringList 		ppp		= stringlist::alloc (3, 1);	// StringList with Class-ID
    char			strid[4000];
    char			name[4000];
    char			temp[4000];

    if (gRun > 1) 	return 0; 	// only once 

    datapool::get_products ("selected ", prod, prod2, prod3, prod4);
    while (num<list::length(prod))
    {
        id1 		= list::get (prod ,num,0);
        id2 		= list::get (prod2,num,0);
        id3 		= list::get (prod3,num,0);
        stringlist::gettext (prod4, num, "", strid);

        strcpy (temp, "get_products %d : \n\n");
        strcat (temp, "id1=%d\n");
        strcat (temp, "id2=%d\n");
        strcat (temp, "id3=%d\n");
        strcat (temp, "stringid via stringlist::gettext='%s'\n");
        strcat (temp, "stringid via stringlist::get='%s'");

        showmessage(temp,
         	num+1,
         	id1, id2,id3,
         	strid,
         	stringlist::get (prod4, num));

        num = num+1;
    }

    num = 0;
    while (num<stringlist::length(ppp))
    {
        stringlist::gettext (ppp, num, "StringID", strid);
        stringlist::gettext (ppp, num, "Num", name);

        strcpy (temp, "alloc by class 3 : entry %d\n\n");
        strcat (temp, "stringid='%s'\n");
        strcat (temp, "name='%s'");

        showmessage(temp, num+1, strid, name);

        num = num+1;
    }

    list::release (prod);
    list::release (prod2);
    list::release (prod3);
    list::release (prod4);
    return 0;
}

Author

Paul Seidel

Version

16.10.2024, 11:40 Uhr

Since

Plugin Version 1.3 (Build 96)

See Also

stringlist

Alphabetic index HTML hierarchy of classes or Java