InstallShield内部库函数之16 列表处理函数
列表被使用来保存相关信息组。在InstallShield中，有两类列表：字符串列表和数字列表。提供两组函数来处理列表：每个处理一种类型。以"Item"结尾的列表函数处理数字列表。以"String"结尾的列表函数处理字符串列表。你不能将数字列表函数使用到字符串列表，反之亦然。下面是在一个安装脚本中处理列表的函数。
ListAddItem
添加一项到一个列表。
ListAddString
添加一个字符串到一个列表。
ListCount
返回在一个指定列表中字符串或数值型元素的数目。
ListCreate
创建一个新的字符串或数字列表。
ListCurrentItem
返回一个列表中的当前项目。
ListCurrentString
返回一个列表中的当前字符串。
ListDeleteItem
删除一个列表中当前项目。
ListDeleteString
删除一个列表中的当前字符串。
ListDestroy
消除一个列表。
ListFindItem
使指定项目成为一个数字列表中的当前项目。
ListFindString
使指定项目成为一个字符串列表中的当前项目。
ListGetFirstItem
从一个数字列表中检索第一个元素。
ListGetFirstString
从一个字符串列表中检索第一个元素。
ListGetNextItem
从一个数字列表中检索当前元素后的元素。
ListGetNextString
从一个字符串列表中检索当前元素后的元素。
ListReadFromFile
读一个文本文件到一个列表。
ListSetCurrentItem
设置一个数字列表中的当前元素。
ListSetCurrentString
设置一个字符串列表中的当前元素。
ListSetIndex
使用一个索引来设置一个列表的当前元素。
ListWriteToFile
写一个字符串列表到一个文件。
16.1 ListAddItem
语法：ListAddItem (listID, nItem, nPlacementFlag);
说明：ListAddItem函数将一个数值型元素添加到一个数字列表中当前元素的前面或后面。为遍历一个列表，首先调用ListGetFirstItem得到列表的第一个元素；然后重复调用ListGetNextItem直到你到达列表尾。为使列表中的一个特定元素成为当前元素，调用ListSetIndex。
参数：
listID
指定一个数字列表的名称。由listID标识的列表必须早已由ListCreate函数初始化。
nItem
指定要添加到列表中的数值型元素。
nPlacementFlag
指定在哪儿放置和当前元素相关的nItem。新元素可以在当前元素之前或之后。在该参数位置传递下列预定义常量之一：
AFTER：将新元素添加到列表中当前元素之后。
BEFORE：将新元素添加到列表中当前元素之前。
返回值：
0：ListAddItem成功添加元素到一个数字列表。
< 0：ListAddItem未能添加元素到一个数字列表。
注解：
·ListAddItem仅工作于数字列表。
16.2 ListAddString
语法：ListAddString (listID, szString, nPlacementFlag);
说明：ListAddString函数添加一个字符串到一个字符串列表中当前元素之前或之后。为遍历一个列表，首先调用ListGetFirstItem得到列表的第一个元素；然后重复调用ListGetNextItem直到你到达列表尾。为使列表中的一个具体元素成为当前元素，调用ListSetIndex。
参数：
listID
指定一个字符串列表的名称。由listID标识的列表必须早已由ListCreate函数初始化。
szString
指定添加到列表中的字符串。
nPlacementFlag
指定在哪儿放置和当前元素相关的szString。新字符串可以在当前元素之前或之后。在该参数位置传递下列预定义常量之一：
AFTER：将新字符串添加到列表中当前元素之后。
BEFORE：将新字符串添加到列表中当前元素之前。
返回值：
0：ListAddString成功添加字符串到列表。
< 0：ListAddString未能添加字符串到列表。
注解：
·ListAddString仅工作于字符串列表。
16.3 ListCount
语法：ListCount (listID);
说明：ListCount函数返回一个列表中的元素数目。
参数：
listID
指定一个字符串或数字列表的名称。
返回值：
>= 0：列表中的项目数。
< 0：ListCount未能确定列表中的元素数。
注解：
·该函数工作于字符串和数字列表。
16.4 ListCreate
语法：ListCreate (nListType);
说明：ListCreate函数创建一个空的字符串或数字列表。记住一个列表不能包括两个类型的元素。InstallShield提供不同的函数组来工作于字符列表和数字列表。你必须不能将一个数字列表的ID用于字符串列表函数，反之亦然。以"Item"结尾的列表函数处理数字列表。以"String"结尾的列表函数处理字符串列表。
当你不再需要列表时，你可以用ListDestroy函数来消除列表。每个列表都有一个指针来标识一个元素为列表的当前元素。不同的列表函数重新定位列表的当前元素。调用任何列表函数时，你必须给该函数传递列表的一个有效ID。确定该函数创建列表成功。否则，所有列表函数因无效列表而失败。
参数：
nListType
指定要创建的列表类型。在该参数位置传递下列预定义常量之一：
NUMBERLIST：指定一个数字列表。
STRINGLIST：指定一个字符串列表。
返回值；
ListID：新创建的空列表的ID。无论何时你要在其它InstallShield列表函数中使用该列表，你都必须使用该ID。你必须检测该变量并确认函数没有返回LIST_NULL。
LIST_NULL (-1)：表明InstallShield未能创建一个列表。那是一个严重内存问题的结果，这是很少见的一种情况。有这样的内存问题时你要继续安装可能会很困难。
注解：
·在你传递一个有效列表ID给任何需要一个列表的函数时，你必须使用ListCreat创建该列表。你可以在一个脚本中创建任意个列表。一个列表可能包含任意个元素。唯一的限制是有效空闲内存的大小。
16.5 ListCurrentItem
语法：ListCurrentItem (listID, nvItem);
说明：ListCurrentItem函数从listID指定的数字列表中检索当前元素。
参数：
listID
指定一个数字列表。
nvItem
返回列表中当前元素的值。
返回值；
0：表明函数成功在一个数字列表中检索当前元素。
< 0：表明函数未能在一个数字列表中检索当前元素。
END_OF_LIST (1)：表明列表为空因而没有一个当前元素。
注解：
·该函数仅工作于数字列表。
·你也可以使用ListGetFirstItem 和ListGetNextItem函数来遍历列表并使任何元素为当前元素。
16.6 ListCurrentString
语法：ListCurrentString (listID, svString);
说明：ListCurrentString函数从listID指定的字符串列表中检索当前元素。
参数：
listID
指定一个字符串列表。
svString
返回列表当前元素的值。
返回值：
0：表明函数成功在一个字符串列表中检索当前元素。
< 0：表明函数未能在一个字符串列表中检索当前元素。
END_OF_LIST (1)：表明列表为空因而没有一个当前元素。
注解：
·该函数仅工作于字符串列表。
·你也可以使用ListGetFirstString 和ListGetNextString函数来遍历列表并使任何元素为当前元素。
16.7 ListDeleteItem
语法：ListDeleteItem (listID);
说明：ListDeleteItem函数从你在listID指定的数字列表中删除当前元素。
参数：
listID
指定从中删除当前元素的数字列表。
返回值：
0：表明函数从一个数字列表中成功删除当前元素。
< 0：表明函数未能从一个数字列表中删除当前元素。
END_OF_LIST (1)：表明列表为空因而没有一个当前元素。
注解：
请参阅ListCurrentItem的注解。
16.8 ListDeleteString
语法：ListDeleteString (listID);
说明：ListDeleteString函数从你在listID指定的字符串列表中删除当前元素。
参数：
listID
指定从中删除当前元素的字符串列表。
返回值：
0：表明函数从一个字符串列表中成功删除当前元素。
< 0：表明函数未能从一个字符串列表中删除当前元素。
END_OF_LIST (1)：表明列表为空因而没有一个当前元素。
注解：
请参阅ListCurrentString的注解。
16.9 ListDestroy
语法：ListDestroy (listID);
说明：ListDestroy函数消除一个列表的内容及列表本身。使用该函数来删除一个listID指定的字符串或数字列表。
参数：
listID
指定要消除的字符串或数字列表。
返回值：
0：表明函数成功消除列表，把它从内存中删除。
< 0：表明函数未能消除列表。
注解：
·该函数既可作用于字符串列表，也可作用于数字列表。一旦一消除了一个列表，不要再在任何列表函数中使用该listID。
·当你不再需要时或在安装脚本结尾时，消除你创建的所有列表。当你消除一个列表，你就释放了和该列表联系的所有内存。
16.10 ListFindItem
语法：ListFindItem (listID, nItem);
说明：ListFindItem函数在一个数字列表中查找一个特定元素，从当前元素开始并从该点继续往下。如果你想从列表头开始查找，使用ListGetFirstItem函数。当ListFindItem找到元素时，它就成为列表的当前元素。
参数：
listID
指定要查找的数字列表。
nItem
指定要在列表中查找的项目。
返回值：
0：表明函数成功找到所要求的元素。
< 0：表明一个错误阻止函数查找指定列表。如，如果由listID指定的列表不存在则会发生错误。
END_OF_LIST (1)：表明InstallShield查找到了列表结尾但没有找到所要求的元素。
注解：
·该函数仅工作于数字列表。
16.11 ListFindString
语法：ListFindString (listID, szString);
说明：ListFindString函数在一个字符串列表中查找一个特定元素，从当前元素开始并从该点继续往下。如果你想从列表头开始查找，使用ListGetFirstString函数。当ListFindString找到元素时，它就成为列表的当前元素。
该函数对字符串比较时区分大小写。
参数：
listID
指定要查找的字符串列表。
szString
指定要在列表中查找的字符串。当查找该字符串时，InstallShield执行一个区分大小写的比较。
返回值：
0：表明函数成功找到所要求的元素。
< 0：表明一个错误阻止函数查找指定列表。如，如果由listID指定的列表不存在则会发生错误。
END_OF_LIST (1)：表明InstallShield查找到了列表结尾但没有找到所要求的元素。
注解：
·该函数仅工作于字符串列表。
16.12 ListGetFirstItem
语法：ListGetFirstItem (listID, nvItem);
说明：ListGetFirstItem函数从一个数字列表中检索第一个元素。该第一个项目成为该列表中的当前元素。
参数：
listID
指定要检索其第一个元素的数字列表。
nvItem
返回数字列表的第一个元素。
返回值：
0：表明函数成功检索了一个数字列表的第一个元素。
-1：表明发生了一个错误阻止函数检索一个数字列表中的第一个元素。
END_OF_LIST (1)：表明列表为空。
注解：
·该函数仅工作于数字列表。
16.13 ListGetFirstString
语法：ListGetFirstString (listID, svString);
说明：ListGetFirstString函数从一个字符串列表中检索第一个元素。该第一个项目成为该列表中的当前元素。
参数：
listID
指定要检索其第一个元素的字符串列表。
svString
返回字符串列表的第一个元素。
返回值：
0：表明函数成功检索了一个字符串列表的第一个元素。
-1：表明发生了一个错误阻止函数检索一个字符串列表中的第一个元素。
END_OF_LIST (1)：表明列表为空。
注解：
·该函数仅工作于字符串列表。
16.14 ListGetNextItem
语法：ListGetNextItem (listID, nvItem);
说明：ListGetNextItem函数检索一个数字列表中当前元素之后的项目。被检索的项目成为该列表中的当前元素。
参数：
listID
指定要从中检索下一个元素的数字列表。
nvItem
返回在数字列表中紧随当前元素的项目。该项目成为列表中的当前元素。
返回值：
0：表明函数成功检索一个数字列表中当前元素之后的元素。
-1：表明发生一个错误阻止函数检索一个数字列表中的指定元素。
END_OF_LIST (1)：表明当前项目是列表中的最后一个元素。
注解：
·该函数仅工作于数字列表。
16.15 ListGetNextString
语法：ListGetNextString (listID, svString);
说明：ListGetNextString函数检索一个字符串列表中当前元素之后的项目。被检索的项目成为该列表中的当前元素。
参数：
listID
指定要从中检索下一个元素的字符串列表。
svString
返回在数字列表中紧随当前元素的项目。该项目成为列表中的当前元素。
返回值：
0：表明函数成功检索一个字符串列表中当前元素之后的元素。
-1：表明发生一个错误阻止函数检索一个字符串列表中的指定元素。
END_OF_LIST (1)：表明当前项目是列表中的最后一个元素。
注解：
·该函数仅工作于字符串列表。
16.16 ListReadFromFile
语法：ListReadFromFile (listID, szFile);
说明：ListReadFromFile函数读一个文本文件到一个列表。一旦你把一个文本文件装入一个列表，你就可以在安装中把它用到不同的函数，如在安装结尾显示一个README文件或用ListWriteToFile写一个字符串列表到磁盘。
该函数让你可以很方便地把整个文件装入到一个列表，而不是一次创建一个列表项。
参数：
listID
返回一个从szFile指定的文件中读入行的列表。由listID 标识的列表必须已经由ListCreat初始化。
szFile
指定将要被读入列表的文件的全限定名。
返回值：
0：表明函数成功将一个文件中的文本行读入到一个列表。
< 0：表明函数未能将一个文件中的文本行读入到一个列表。
注解：
·该函数检测每个字符串结尾的换行符并使用这些字符作为列表中每个元素的分界符。
·该函数仅作用于字符串列表和文本文件。
16.17 ListSetCurrentItem
语法：ListSetCurrentItem (listID, nItem);
说明：ListSetCurrentItem函数将nItem的值赋给一个数字列表中的当前元素。
参数：
listID
指定其当前元素要被更新的数字列表的名称。由listID标识的列表必须早以由ListCreat初始化。
nItem
指定将要置换当前元素的数值型值。
返回值：
0：表明函数成功更新数字列表中的当前元素。
< 0：表明函数未能更新数字列表中的当前元素。
END_OF_LIST (1)：表明列表为空。
注解：
·该函数仅工作于数字列表。
16.18 ListSetCurrentString
语法：ListSetCurrentString (listID, szString);
说明：ListSetCurrentString函数将szString的值赋给一个字符串列表中的当前元素。
参数：
listID
指定其当前元素要被更新的字符串列表的名称。由listID标识的列表必须早以由ListCreat初始化。
szString
指定将要置换当前元素的字符串型值。
返回值：
0：表明函数成功更新字符串列表中的当前元素。
< 0：表明函数未能更新字符串列表中的当前元素。该错误的通常的原因是下标超出有效列表元素的范围。
注解：
·该函数仅工作于字符串列表。
16.19 ListSetIndex
语法：ListSetIndex (listID, nIndex);
说明：ListSetIndex函数使用一个下标来指定一个字符串列表或数字列表中的一个特定元素为当前元素。你也可以使用使用一个常量来一次检索列表中的一个元素或跳到列表的头或尾。通过使用下标来访问列表中的项，你可以将数字列表或字符串列表处理为队列。
下标数从0开始。例如，如果你在参数nIndex中输入5，则列表中的第六个物理位置的项成为当前元素。使用ListCurrentItem 和 ListCurrentString来检索当前元素的值。
参数：
listID
指定其下标要被设置的字符串列表或数字列表的名称。
nIndex
指定你要设置为当前元素的元素的数。列表元素从0开始计数。在该参数位置传递一个数值型值或下列预定义常量之一：
LISTFIRST：移动到列表的第一个元素。
LISTLAST：移动到列表的最后一个元素。
LISTNEXT：移动到列表的下一个元素。
LISTPREV：移动到列表的前一个元素。
返回值：
0：表明函数成功更新列表中的当前元素。
< 0：表明函数未能更新列表中的当前元素。
END_OF_LIST (1)：表明下标超出有效列表元素的范围。
注解：
·在你设置被索引的元素为当前元素后，你可以在脚本中使用ListCurrentItem 或 ListCurrentString函数来检索被索引（当前）项的值。
·该函数可工作于字符串列表和数字列表。
16.20 ListWriteToFile
语法：ListWriteToFile (listID, szFileName);
说明：ListWriteToFile函数将一个字符串列表写到一个文本文件。每个字符串显示在文本文件中分隔的行中。
参数：
listID
指定写到一个文本文件中的字符串名。
szFileName
指定要写字符串列表到其中的文件的全限定名。如果文件不存在，则被创建。如果文件已经存在，则它被修改。
返回值：
0：函数成功。
< 0：函数失败。
