InstallShield内部库函数

InstallShield内部库函数

下载资源：点击

1  库函数综述

InstallShield包含300多个内部库函数，用户可在安装脚本中调用它们来创建程序组，操作文件夹，处理目录，监督安装状态，创建对话框，操作文件及其它更多工作。因为InstallShield脚本编译器已经识别这些库函数名，所以用户在使用它们之前无须说明。

为了成功调用一个内部库函数，用户必须知道库函数名称及使用格式。InstallShield 库函数参阅附录D库函数索引。在接下去的几节中我们将对其中主要的一些库函数作详细介绍。在这里先简单向用户描述一下库函数的构成。

如：AskYesNo是一个库函数，它在对话框中显示一个询问，然后等待最终用户通过点击按扭来响应，Yes或No。AskYesNo格式如下： AskYesNo(szQuestion,nDefault)。这个格式显示了正确的函数名，括号中显示了函数的参数列表。在函数的详细说明帮助中，每个参数用匈牙利标记法表示，指出每个参数位置上可被接受的数值类型。AskYesNo要求两个参数：第一个是字符类型，第二个是数值型。

与C语言一样，InstallShield区分大小写，因此用户要严格注意库函数名称中大写字母。

在用户的脚本中使用任何库函数，传递的参数数目一定要正确，并且要确保传递的每个参数值符合该位置规定的类型。如果用户传递了错误的参数数目或者在任何一个或几个参数位置传递了不相符的数值类型，脚本都不能被编译。

注意:

．作为参数传递的字符串必须包括在单引号或者双引号内。

如：“Please wait while files are transferred”，或‘This is a string’或“c:\\Myfolder\\myfile.txt”

．InstallShield 不允许将一个赋值语句作为参数传递。另外，用户在一个函数变量中不能使用&&或||运算符。

．由一个调用传递给一个函数的可变长字符串变量在被调用函数中不能自变长。如果函数试图赋一个值，该值的长度超过参数的现有长度，则会发生401运行错误。为避免这个错误，在调用将字符串传递给一个函数时就要为字符串指定一个特定长度。

2  用户界面函数

用户界面函数允许用户自定义特定的错误信息及错误框标题。然而，一些在安装开发中遇到的内部错误信息是不能由用户界面函数来修改的。这部分主要对用户界面函数的语法、描述、参数等作详细说明。

2.1  Disable函数

语法：Disable(nConstant)

说明：Disable函数使由参数nConstant指定的用户界面对象或安装特性无效。

参数：

nConstant

指定用户界面对象或可操作特性使其无效，在这个参数位置传递下列预定义常量之一：

BACKBUTTON：使在一些内部对话框中显示的Back按钮无效（即使其变灰显示），Back按钮缺省置为有效。

BACKGROUND：使安装主背景窗口无效且隐藏。注意：当安装处于全屏幕方式时该参数不起作用。

BILLBOARD：在安装过程中取消布告板的显示。

DIALOGCACHE：使对话缓冲机制无效。有关对话缓冲的详细说明，请参阅Enable。

HOURGLASS：使光标由一个“忙”光标（缺省为沙漏光标）改变为标准光标（缺省为一个指针）。

INDVFILESTATUS：使路径及文件名在文件传输时不显示在进度指示器（状态条）中。

LOGGING：不记录卸载信息，使信息不记录在卸载日志文件中。注意：记录功能由函数DeinstallStart自动置为有效。在调用DeinstallStart之前置记录卸载信息无效将不起任何作用，因为当DeinstallStart被调用时，记录功能将被自动激活，用户必须就在不应被记录的卸载操作执行之前手控禁止记录。

NEXTBUTTON：使一些内部对话框的Next按钮无效（使其变灰显示）。Next按钮缺省置为有效。

SELFREGISTERBATCH：使注册自注册文件的批处理方法无效。详细说明请参阅Enable。

SATAUS：使标准进展指示器（状态条）无效且隐藏。

STATUSDLG：使对话框形式的进展指示器（状态条）无效且隐藏。

STATUSEX：禁止以显示安装状态对话框来取代进度指示器（状态条）。

STATUSOLD：使原风格的进度指示器（状态条）无效且隐藏。

返回值：

 0：说明函数成功禁止了由参数nConstant指定的用户界面对象或安装特性。

<0：说明函数未能禁止由参数nConstant指定的用户界面对象或安装特性。

注解：

·如果用户的脚本中调用Disable函数来禁用Next或Back按钮，那么在函数被调用后的所有对话框中该按钮均被禁用，为激活Next或Back按钮，用户需带相应的常量来调用Enable。

·DIALOGCACHE在没有Next 或Back按钮的对话框中不起作用。

2.2  Enable函数

语法：Enable (nConstant);

说明：Enable函数激活由参数nConstant指定的用户界面对象或安装特性。

参数：

nConstant

指定你要激活的用户界面对象或操作特性。在该参数位置传递下列预定义常量之一：

BACKBUTTON：激活显示在一些内部对话框中的Back按扭。缺省时Back按扭是被激活的，但可以通过调用Disable函数来禁用它。

BACKGROUND：当安装是在窗口方式时，显示安装主背景窗口。当安装是缺省的全屏幕方式时，该常量没有作用。为激活窗口方式，你必须以常量DEFWINDOWMODE或 FULLWINDOWMODE来调用Enable。

DEFWINDOWMODE：配置主背景窗口为一个有标题栏的标准窗口。如果背景窗口被激活，它的外观将会立即改变。如果背景窗口被禁用，屏幕不会被修改直到带常量BACKGROUND调用Enable时。

DIALOGCACHE：激活对话框缓冲机制，它可以消除在显示对话框之间出现的屏幕闪烁。这种屏幕闪烁在运行于窗口方式的安装的标题栏中特别明显。注意对话框缓冲机制仅工作于有BACK和NEXT按扭的对话框。缺省时对话框缓冲被禁用。

FULLWINDOWMODE：设置主背景窗口为一个有标题栏的最大化窗口。如果背景窗口被激活，它的外观将会立即改变。如果背景窗口被禁用，屏幕不会被修改直到带常量BACKGROUND来调用Enable时。

HOURGLASS：使光标改变为“忙”光标，缺省为一个沙漏光标。

INDVFILESTATUS：当调用ComponentTransferData、 CopyFile、 或XcopyFile并且进度指示器被激活时，激活显示每个文件的全限定名（在进度指示器的第二行中显示）。注意，在一个运行基于事件的脚本的安装程序中，ComponentTransferData被自动调用。

LOGGING：激活存入卸载记录功能。当存入功能被激活时，InstallShield存入的卸载记录的操作结果将被记录在卸载日志文件中，并将在卸载过程中被反向。自动调用DeinstallStart激活存入功能；因此，你不需要手动激活存入功能除非你先前用Disable函数禁用了它。

NEXTBUTTON：激活显示在一些内部对话框中的Next按扭。Next 按扭缺省为激活。

SELFREGISTERBATCH：激活注册自注册文件的批处理方法。该方法使用来避免和自注册文件相关联的依赖性问题。缺省为标准（非批处理）自注册。

    有关批处理方法的更多信息如下：

·在文件组窗格中，高亮显示你的自注册文件的文件组文件夹。它的属性表在打开在右边。

·双击Self-Registered域，则自注册页打开。

·选择"Yes, all the files in this file group are self-registering"单选钮。

·打开你的安装脚本（在Scripts窗格中找到Setup.rul）。

` 在你传输文件前，以SELFREGISTERBATCH选项调用Enable函数。所有自注册文件放在一个内部队列中，也就是，当它们被安装时它们会被立即注册。（在一个使用基于事件脚本的安装程序中，OnBegin处理程序被调用前，Enable(SELFREGISTERBATCH)会被自动调用。）

传输文件后，以SELFREGISTRATIONPROCESS选项调用Do函数。当你调用Do(SELFREGISTRATIONPROCESS)时，InstallShield注册所有自注册文件。如果当Do被调用时，系统变量BATCH_INSTALL等于TRUE（表明需要一个重启来完成该安装）,则注册自注册文件被延迟到重启后。

　　在你调用Do(SELFREGISTRATIONPROCESS)后，你可以检查自注册是否成功。如果因任何原因Do失败了，它会返回-1。那些自注册失败的文件的名称被保存在系统变量ERRORFILENAME中，由一个分号分隔。

例如，下列代码将所有自注册文件注册在文件媒体库中。

// Enable batch method to queue self-registering files.

Enable ( SELFREGISTERBATCH );

// Install files.

nResult = ComponentTransferData( MEDIA );

// Register the files, check for errors.

if Do ( SELFREGISTRATIONPROCESS ) < 0 then

szMsg = "File(s) failed to self-register: \n" + ERRORFILENAME;

MessageBox (szMsg, WARNING);

endif;

STATUS：激活显示标准进度指示器（状态栏）。

STATUSDLG：激活显示对话框风格的进度指示器（状态栏）。

STATUSEX：激活显示安装状态对话框来取代进度指示器（状态栏）。

STATUSOLD：激活显示旧风格进度指示器（状态栏），它没有一个 Cancel按扭。

返回值：

0：表明函数成功激活由参数nConstant指定的用户界面对象或安装特性。

< 0：表明函数未能激活由参数nConstant指定的用户界面对象或安装特性。

注解：

·缺省时，安装运行在全屏方式；主背景窗口显示为一个没有标题栏的全屏窗口。这种方式中，主安装窗口不能被调整大小并且没有一个可见的标题栏。为激活窗口方式，你必须以常量DEFWINDOWMODE 或 FULLWINDOWMODE来调用Enable。

·如果你的脚本中调用Disable函数来禁用Next或Back按钮，那么在函数被调用后的所有对话框中该按钮均被禁用，为激活Next或Back按钮，你需带相应的常量来调用Enable。

·DIALOGCACHE在没有Next 或Back按钮的对话框中不起作用。

2.3  FindWindow

语法：FindWindow (szClassName, szWinName);

说明：FindWindow 函数通过指定一个窗口的窗口类和窗口名为高级开发人员提供一个得到窗口句柄的方法。如果你知道了一个应用程序的窗口类和窗口名，就可得到它的句柄。然后你可以通过这个句柄直接发送信息给该窗口。

参数：

szClassName

指定窗口所属类的名字。若指定为“任意类”，则在该参数处传递一个空字符串。

szWinName

指定窗口标题。为返回指定类中最顶层窗口的句柄，在该参数处传递一个空字符串（“”）。

返回值：

XXXX：窗口的句柄。

NULL (0)：FindWindow根据指定的窗口名和类名不能找到该窗口。

注解：

·要找到一个窗口的类和名字，可运行Microsoft Spy.exe程序。

2.4  PlaceBitmap

语法：PlaceBitmap (szName, nID_BITMAP, nDx, nDy, nDrawOp);

说明：PlaceBitmap函数在安装窗口中插入一个图象。图象来源由szName指定，它可以是一个位图文件（.bmp），图元文件(.wmf)，或者是动态链接库（.dll）。InstallShield支持2色、16色、256色和真彩色位图（bitmap）。2色、16色、256色位图可有透明部分。

    透明位图在显示可与背景窗口组合显示的图象时有用。在位图中与指定的透明色匹配的像素不会被显示；在该位置的背景像素保持可见。在安装中，一个有技巧的设计常常用包含有公司名称和徽标的透明位图来作为安装窗口的标题。

    为指定一个透明位图，你必须给参数nDrawOp位置传递一个常量BITMAPICON。你也必须考虑在一个位图中什么颜色被置为透明。缺省的透明色是purple(RGB(255,0,255))。要指定一个不同的透明色，可用下面描述的参数szName来指定。

因为图元文件（metafile）是绘制的，而不是放置的，它们固有为透明。如果BITMAPICON被指定为一个图元文件，则该参数被忽略。

    通过使用SetDisplayEffect函数可以显示非透明位图的许多特殊显示效果。该函数也为图元文件提供了有限的显示效果。

窗口中位图的位置可以用两种方法中的一种来指定：

·通过参数nDrawOp来传递位置常数。

·通过参数nDx与nDy来传递距安装窗口边缘的垂直和水平位移。 

通常可通过调用PlaceBitmap（将参数nDrawOp设置为REMOVE）来删除任何不再需要的位图文件和图元文件。建议删除不需要的位图，即使该位图可以被其他位图完全覆盖，因为第一个位图的调色板入口只有在位图被删除后才会被释放。

　　一个真彩色位图显示在一个运行于16色或256色模式的系统上时，只用那些在调色板中有效的颜色；不会给位图分配附加的颜色，即使附加调色板入口是有效的。若你希望含有24位位图的安装可在16色或256色的系统中运行，需要包含该位图的16色或256色的版本。然后在选择要显示的位图前带参数COLORS调用GetSystemInfo来确定当前颜色模式。

参数：

szName

指定要被显示图象的位图文件、图元文件的全限定名或动态链接。InstallShield通过扩展名来识别位图文件和图元文件。位图文件必须有扩展名.bmp,图元文件必须有扩展名.wmf.动态链接必须有扩展名.dll。如果一个文件名指定为没有扩展名，InstallShield将假定其扩展名为.dll。

　　为指定一个候选透明色，在文件名后放置一个分号（；），后随一组RGB颜色值（RGB颜色由三个数值指定，由逗号分隔）。该颜色被用作由szName指定的位图的透明色。注意它对于已经被显示的位图不起作用，也不会成为随后调用PlaceBitmap而显示的位图的缺省透明色。

下面的参数指定白色为透明色：

SUPPORTDIR ^ "Bitmap.bmp;255,255,255" 

当nDrawOptions设置为 REMOVE时，该参数被忽略。

nID_BITMAP

指定驻留在一个.dll中的位图的资源ID。如果位图的源点是图元文件或位图文件，指定一个在当前显示的图象中没有使用的数值；所有同时显示的图象必须有其唯一的ID号。当nDrawOptions设置为REMOVE，该参数必须包含显示的图象的ID。

nDx

当nDrawOp设置为LOWER_LEFT, LOWER_RIGHT, UPPER_LEFT, 或 UPPER_RIGHT时以像素点指定安装窗口边缘和图象边缘之间的水平距离；否则该参数被忽略。

nDy

当nDrawOp设置为LOWER_LEFT, LOWER_RIGHT, UPPER_LEFT, 或 UPPER_RIGHT时以像素点指定安装窗口边缘和图象边缘之间的垂直距离；否则该参数被忽略。

nDrawOp

指定位图放置的位置，设置放置选项，或者删除先前放置的位图。给该参数传递下列预定义好的常数：

BITMAPICON：指出位图有透明部分。用户可以用按位或运算符（｜）来将该常量和其他常量（除TILED、FULLSCREEN或FULLSCREENSIZE外）组合。当BITMAPICON和那些常量之一组合时，按位或运算被忽略，而只使用BITMAPICON。

TILED：位图在主安装窗口平铺。该常量通常被用来创建一个安装背景。当该常量被指定时，即使位置选项被忽略，特殊效果已被SetDisplaytEffect激活，位图仍正常显示。

FULLSCREEN：拖拉图象使其填充整个安装窗口。拖拉时图象不会被调整大小。如果一个位图图象比InstallShield主窗口小，它在窗口中被置中，背景由当前背景色填充。缺省值为深青色（teal）；可以通过使用SetColor函数来改变。当这个常量被指定时，位置选项被忽略，即使一个特殊效果已经被SetDisplayEffect激活，位图仍正常显示。

FULLSCREENSIZE：拖拉和伸展图象使其填充满整个安装窗口。当这个常量被指定时，位置选项被忽略，即使一个特殊效果已经被SetDisplayEffect激活，位图仍正常显示。

CENTERED：将位图置于InstallShield安装窗口的中央。

LOWER_LEFT：将位图置于InstallShield安装窗口的左下角。

LOWER_RIGHT：将位图置于InstallShield安装窗口的右下角。

UPPER_LEFT：将位图置于InstallShield安装窗口的左上角。

UPPER_RIGHT：将位图置于InstallShield安装窗口的右上角。

REMOVE：删除一个先前放置的位图或图元。任何由SetDisplayEffect激活的特殊效果被忽略。

返回值：

0：表明函数成功找到和放置图象。

< 0：表明函数未能找到或放置图象。

注解：

·调用SetDisplayEffect来为非平铺、全屏幕、透明位图设置特殊效果；用户也可以用它为图元设置有限的特殊效果。

·InstallShield不支持24位透明位图。如果用户在一个24位位图中包含了透明色而且指定了BITMAPICON常量，该颜色将被正常显示。

·当你在运行256色模式的系统中放置一个256色的位图时，InstallShield将试图分配位图的调色板到系统调色板。如果多个256色位图被放置，InstallShield将试图将所有可视位图的调色板合并到系统调色板，优先为最近放置的位图。这种行为可能导致在其他位图被显示时先前放置的位图改变颜色。

·在一个运行在有256色抖动背景的256色模式的系统中，含有许多颜色的位图可能导致一些给背景使用的调色板入口被重新分配；这可引起在背景中出现一种梯度效果。如果安装中包含了使用多种颜色的位图，则当它们运行在256色系统中时应不要使用256色抖动背景。

·系统调色板仅存在于运行在256色模式的系统中。运行在windows 95和其后高彩色或者真彩色模式下的系统及运行在65525（16位）色模式Windows NT下的系统中都没有系统调色板。这些系统中不用考虑调色板句柄问题。颜色使用RGB值来直接显示。

·因为图元文件是被着色的，它们不包括一个自定义调色板。当一个图元文件在一个256色系统中显示时，不发生调色板处理；图元文件是用当前调色板中有用的颜色绘制而成。由此，若要运行在256色系统中，用户在安装程序中不应该使用显示颜色不同于标准16色的图元文件。

2.5  PlaceWindow

语法：PlaceWindow (nObject, nDx, nDy, nCorner);

说明：PlaceWindow函数改变用户界面对象的位置，包括布告牌。用nDx和nDy指定对象的边与屏幕边缘的距离。

参数：

nObject

指定要被改变位置的对象。在该参数位置传递下列预定义的常量之一：

BACKGROUND：移动背景窗口。

BILLBOARD：设置在文件传输过程中使用的布告牌的位置。

MMEDIA_AVI：设置要播放的下一个AVI文件的窗口位置。缺省时，AVI文件将在InstallShield客户窗口的左边位置窗口中播放，从左起10个像素点，从上起10个像素点。

STATUS：移动进度指示器。

STATUSDLG：移动对话框风格的进度指示器。

STATUSEX：移动安装状态对话框。

STATUSOLD：移动旧风格的进度指示器。

当你调用PlaceWindow来移动进度指示器或者状态对话框时，确信为你在安装中激活的反馈对象传递了正确常量。例如，如果你调用了Enable(STATUSOLD),则你必须传递STATUSOLD给PlaceWindow。

nDx

以像素点指定对象的边与屏幕边缘之间的水平距离。

nDy

以像素点指定对象的边与屏幕边缘之间的垂直距离。

nCorner

指定用nDx和nDy表示的距离是从哪个角度量所得。在该参数位置传递下列预定义的常量之一：

LOWER_LEFT：从InstallShield主窗口的左边度量得nDx，从底端度量得nDy。

LOWER_RIGHT：从InstallShield主窗口的右边度量得nDx，从底端度量得nDy。

UPPER_LEFT：从InstallShield主窗口的左边度量得nDx，从顶端度量得nDy。

UPPER_RIGHT：从InstallShield主窗口的右边度量得nDx，从顶端度量得nDy。

返回值：

0：表明函数成功改变了对象的位置。

< 0：表明函数未能改变对象的位置。

注解：

·使用该函数时要意识到一个安装程序要运行在不同的屏幕分辨率下。你在放置对象前可能要确定屏幕范围。距离以像素点度量，是对象边缘与指定的屏幕角落边缘之间的距离。

·用户不能用该函数定位消息框，因为消息框是由本机的Windows/PM API创建。一个消息框的位置由Windows/PM确定，而不是在InstallShield控制之下。另外，用户不能用该函数定位一个自定义对话框。

2.6  PlayMMedia

语法：PlayMMedia (nType, szFileName, nOperation, nReserved);

说明： PlayMMedia函数播放一个声音或AVI文件。MIDI或WAVE类型的声音文件和AVI(视频)文件既可以以同步方式也可以以异步方式播放。该函数也可以被用来连续播放一个文件。为了实现这个目的，一个标志可被按位或，来指示该文件以连续方式被播放。

    由于 AVI文件早被压缩而且往往大于1.4MB的软盘，因此,视频显示推荐于光盘安装。

参数：

nType

指定文件类型。在该参数位置传递下列预定义的常量之一：

MMEDIA_WAVE：文件是WAVE声音格式。

MMEDIA_MIDI：文件是MIDI声音格式。

MMEDIA_AVI：文件是一个AVI文件。

szFileName

指定要播放的声音/AVI文件的全限定名。

nOperation

指定播放方式。在该参数位置传递下列预定义的常量：

MMEDIA_PLAYSYNCH：同步播放。

MMEDIA_PLAYASYNCH：异步播放。该常量可以用或运算符（|）与MMEDIA_PLAYCONTINUOUS组合使用。

MMEDIA_PLAYCONTINUOUS：连续循环播放。当以同步方式播放一个声音/AVI文件时不能使用该值。它只使用于以异步方式播放的文件。用或运算符（|）将它与MMEDIA_PLAYASYNCH组合使用。

MMEDIA_STOP：停止播放。

nReserved

给该参数传递0值，不允许其他值。

返回值：

0：表明函数成功播放文件。

< 0：表明函数不能播放文件。

2.7  RGB

语法：RGB (constRed, constGreen, constBlue);

说明：RGB函数创建一个自定义颜色值，该颜色可被SetColor和SetTitle使用。

参数：

constRed

指定一个数值型常数，值域为0..255，指示在自定义色中红色的数量。

constGreen

指定一个数值型常数，值域为0..255，指示在自定义色中绿色的数量。

constBlue

指定一个数值型常数，值域为0..255，指示在自定义色中蓝色的数量。

返回值：

该函数返回一个调用SetColor和SetTitle时可被使用的自定义颜色的数值。

2.8  SetColor 

语法：SetColor (nObject, nColor);

说明：SetColor函数设置主安装窗口的背景色。

参数：

nObject

指定要改变的用户界面对象。在该参数位置传递下列预定义的常量：

BACKGROUND

指示安装窗口的背景。缺省颜色为纯深青色（solid teal）：RGB(0,128,128)。

nColor

为背景指定一种颜色。

对于一种过渡背景色，可传递下列常量之一：

BK_BLUE、BK_GREEN、BK_MAGENTA、BK_ORANGE

BK_PINK、BK_RED、BK_YELLOW  

对于一种纯背景色，可传递下列常量之一：

BK_SOLIDBLACK、BK_SOLIDBLUE、BK_SOLIDGREEN、BK_SOLIDMAGENTA

BK_SOLIDORANGE、BK_SOLIDPINK、BK_SOLIDRED、BK_SOLIDWHITE

BK_SOLIDYELLOW

对于一种自定义颜色，可在该参数位置传递RGB函数。

为了在使用自定义颜色绘制背景时得到光滑的效果（过渡），可将该颜色与预定义常量BK_SMOOTH按位或。注意当256色有效时光滑效果将更好。

返回值：

0：表明函数成功设置对象的颜色。

< 0：表明函数未能设置用户界面对象的颜色。

注解：

·当使用一个RGB值时，你可以应用Microsoft Windows的编程指南中描述的相同的方法。

你可以指定RED、GREEN、BLUE颜色的混合来“混合”颜色。用从0到255的数之一来表示使用颜色的数量。在RGB宏中的参数必须使用字面数值。你可以使用一个表示RGB颜色的长整型数来代替RGB语句。

2.9  SetDialogTitle 

语法：SetDialogTitle (nDialogId, szTitle);

说明：SetDialogTitle函数改变显示在一些公用内部对话框标题栏的标题。用参数nDialogId指定对话框。如果你不使用SetDialogTitle，InstallShield显示缺省标题。一旦你为某一特定对话框设置了标题，除非你再次使用SetDialogTitle改变标题，否则InstallShield在每一个该类型对话框的实例中都使用该标题。

参数：

nDialogId

标识标题要被改变的内部对话框。在该参数位置传递下列预定义常量之一：

DLG_ASK_OPTIONS：改变AskOptions对话框标题。

DLG_ASK_PATH：改变AskPath对话框标题。

DLG_ASK_TEXT：改变AskText对话框标题。

DLG_ASK_YESNO：改变AskYesNo对话框标题。

DLG_ENTER_DISK：改变EnterDisk对话框标题。

DLG_MSG_INFORMATION：改变信息风格的消息框的标题。

DLG_MSG_SEVERE：改变严重警告风格的消息框的标题。

DLG_STATUS：改变对话风格进度指示器的标题。在带DLG_STATUS选项调用SetDialogTitle后，为了使标题修改有效，你必须通过调用Enable(STATUSDLG)来重新激活该对话风格进度指示器。

DLG_MSG_WARNING：改变警告风格的消息框的标题。

DLG_USER_CAPTION：当你使用用户定义的消息框风格时改变消息框的标题。

szTitle

指定新标题。

返回值：

0：表明函数成功修改了对话框标题。

< 0：表明函数未能修改对话框标题。

注解：

·你必须为每种你希望修改其标题的对话框分别调用SetDialogTitle。

·InstallShield使用标准Windows消息框函数创建消息框。Windows为这些消息框确定Ok和Cancel按扭文字。InstallShield不能控制在Windows 消息框中使用的按扭文字。

2.10  SetDisplayEffect 

语法：SetDisplayEffect (nEffect);

说明：SetDisplayEffect函数指定用PlaceBitmap函数显示位图文件或图元文件时使用的显示效果。一旦显示效果被设定，所有随后由PlaceBitmap显示的位图文件将一直使用该效果显示，直到另一个对SetDisplayEffect的调用来设定一个新的显示效果。

参数：

nEffect

指定一个显示效果。在该参数位置传递下列预定义的常量之一。注意这些常量具有互斥性；它们相互之间不能使用按位或。而且，当用PlaceBitmap显示一个位图文件时指定了BITMAPICON、 FULLSCREEN、 FULLSCREENSIZE或 TILED时该参数无效：

EFF_FADE：位图或布告牌淡入淡出。

EFF_REVEAL：位图或布告牌逐渐从中央向四周填充。

EFF_HORZREVEAL：位图或布告牌从它的中央逐渐水平滚动出来。

EFF_HORZSTRIPE：位图或布告牌的一部分从外往里水平填充，然后剩余部分从中央部分往外填充。

EFF_VERTSTRIPE：位图或布告牌的一部分从外往里垂直填充，然后剩余部分从中央部分往外填充。

EFF_BOXSTRIPE：位图或布告牌的一部分从四周向里填充，剩余部分向四周填充。

EFF_NONE：该选项是缺省设置。使用它来清除调用其它任一选项后的显示效果。

只有EFF_REVEAL和EFF_HORZREVEAL可用于图元文件。

返回值：

0：表明函数成功设置显示效果。

< 0：表明函数未能设置显示效果。

注解：

·当位图是由PlaceBitmap带选项BITMAPICON、FULLSCREEN、FULLSCREENSIZE或TILED显示时，该位图不会按显示效果显示，而是正常显示。更多的信息可查阅PlaceBitmap。

·显示效果仅当放置位图时出现，当删除位图时不能使用显示效果。

·只有展示（EFF_REVEAL）和水平展示（EFF_HORZREVEAL）效果可用于图元文件。

2.11  SetErrorMsg

语法：SetErrorMsg (nErrorID, szText);

说明：SetErrorMsg函数定制InstallShield缺省错误信息。你可以使用该函数来指定显示这些错误信息的消息框的标题文本。

参数：

nErrorID

指定要替换的错误信息。在该参数位置传递下列预定义的常量之一：

ERR_BOX_BADPATH：当EnterDisk检测到一个由用户输入的错误路径时显示该信息。

ERR_BOX_BADTAGFILE：当EnterDisk检测到指定的标签文件不存在于磁盘上时显示该信息。

ERR_BOX_DISKID：当EnterDisk检测到由用户指定的驱动器不存在时显示该信息。

ERR_BOX_DRIVEOPEN：当EnterDisk检测到磁盘驱动器未关闭时显示该信息。

szText

指定要在消息框中显示的错误信息。

返回值：

0：表明函数成功改变错误信息。

< 0：

表明函数未能改变错误信息。

2.12   SetErrorTitle 

语法：SetErrorTitle (nErrorID, szText);

说明：SerErrorTitle函数指定InstallShield内部错误消息框标题栏的自定义文本。你可以使用该函数来自定义错误消息文本。

参数：

nErrorID

指定标题要被替换的错误消息框。在该参数位置传递下列预定义的常量之一：

ERR_BOX_BADPATH：当EnterDisk检测到错误路径时显示该消息。

ERR_BOX_BADTAGFILE：当EnterDisk检测到指定的标签文件不存在于磁盘上时显示该消息。

ERR_BOX_DISKID：当EnterDisk检测到指定的驱动器不存在时显示该消息。

ERR_BOX_DRIVEOPEN：当EnterDisk检测到磁盘驱动器未关闭时显示该消息。

szText

指定显示在错误消息框中的标题。

返回值：

0：表明函数成功修改了标题栏的文本。

< 0：表明函数未能修改标题栏的文本。

2.13  SetFont

语法：SetFont (nItemID, nFontStyle, szFontName);

说明：SetFont函数设置显示的正文串的字体和风格。你可以在该函数使用标准Windows

      字体。

参数：

nItemID

指定其字体和字体风格要被设置的项。在该参数位置传递下列预定义的常量：

FONT_TITLE：指定安装过程的主标题，该主标题显示在安装窗口的左上角。

nFontStyle

指定字体风格。在该参数位置传递下列预定义的一个或多个常量。除STYLE_NORMAL之外的所有常量可以用按位或来指定多种风格：

STYLE_NORMAL：没有加粗、倾斜或阴影（不能被按位或）。

STYLE_BOLD：字体加粗。

STYLE_ITALIC：字体倾斜。

STYLE_SHADOW：字体有阴影底纹。

STYLE_UNDERLINE：加下划线。

szFontName

指定一个有效的Windows字体的名称。有效的字体名称包括Courier, Helv, Helvetica, Modern, Roman, Script, Terminal, Times 和TmsRmn。如果指定的字体没有找到指定的风格，就使用Arial。

返回值：

0：表明函数成功设置字体。

< 0：表明函数未能设置字体。

2.14  SetStatusWindow

语法：SetStatusWindow (nPercent, szString);

说明：SetStatusWindows函数为进度指示器（状态条）设置完成指示器的百分比的初始值或当前值，并指定在进度指示器（状态条）最高行显示的当前消息。

　　通过调用ComponentTransferData或ComponentMoveData来传输文件的安装必须在文件传输开始之前调用SetStatusWindows，这是为了设置完成指示器百分比为0%而且清除指示器最高行。不再需要另外调用SetStatusWindows。每一个组件的文件被装入时，该组件的 ‘状态文本’字符串会在状态条最高行自动显示。

　　使用CopyeFile或XcopyFile函数装入文件的安装程序在相继调用CopyFile或XcopyFile之间，可能需要多次调用SetStatusWindows来改变指示器最高行的信息。

　　在传输文件前，你的安装程序还应该调用StatusUpdate函数激活文件传输过程中百分比完成指示器的自动更新。为了使得在状态条第二行显示正被安装文件的名称和路径，需在传输文件前带参数INDVFILESTATUS来调用Enable函数。在这些调用后，百分比完成指示器在文件传输过程中被平滑更新，每个文件的文件名在被传输时将显示。

参数：

nPercent

指定0到100之间的一个数值来表示百分比完成指示器显示的百分比。若要改变显示在状态条最高行的信息而不改变百分比完成指示器，则指定该参数为-1。

szString

指定显示在状态条最高行的字符串。注意如果一个'DisplayText'参数已被指定给该组件（在IDE中），那么当调用ComponentTransferData时该字符串将自动改写任何该参数指定的文本。

返回值：该函数没有返回值。

2.15  SetTitle

语法：SetTitle (szTitle, nPointSize, nColor);

说明：SetTitle函数根据nColor的值在主窗口标题栏或在主窗口内显示一个标题。

参数：

szTitle

指定在主窗口标题栏或主窗口内显示的一个标题。如果标题要显示在窗口的标题栏，你必须在第三个参数位置指定预定义常量BACKGROUNDCAPTION。如果一个标题栏的标题不符合可用空间，那将被从右截尾并以省略号终止。缺省标题栏标题为“安装”。

当给第三个参数传递一个颜色值时，标题在主窗口的顶端左对齐显示。相对主窗口太宽的标题将被从右截尾显示。为创建一个占据多行的标题，可在你希望的行断开处嵌入换行符。

nPointSize

以点数来指定一个在主窗口显示的标题的字号。建议字号为24点数。注意当第三个参数为BACKGROUNDCAPTION时该参数被忽略。

nColor

指定一个颜色或预定义常量BACKGROUNDCAPION。为指示szTitle值应该在主窗口标题栏显示，则在该参数位置传递预定义的常量BACKGROUNDCAPTION。当用户指定了BACKGROUNDCAPTION，nPointSize被忽略；标题栏标题的颜色和字号将由最终用户的系统设置决定。注意该选项在不运行在窗口模式的安装程序中无效；请查看下面的注解。

为指示szTitle值应该在主窗口中显示，通过在该参数位置传递下列预定义的常量之一来指定该标题的颜色：BLACK，BLUE，GREEN，MAGENTA，RED，YELLOW或WHITE。用户也可以在该参数位置传递RGB函数来指定自定义颜色，如下面例子所示：

   SetTitle("FantasticApp", 24, RGB(78, 125, 161));

返回值：

0：表明函数成功设置安装的标题。

< 0：表明函数未能设置安装的标题。

注解：

·不运行于窗口模式下的安装中，第三个参数设置为BACKGROUNDCAPTION时调用SetTitle无效。为在一个标准窗口中运行安装程序，你必须首先以参数DEFWINDOWMODE或FULLWINDOWMODE来调用Enable，然后以参数BACKGROUND调用Enable来显示窗口。

·用SetColor来设置你安装的背景色。

·用SetFont来设置在背景窗口中显示的标题的字体和字体风格。

2.16  SizeWindow

语法：SizeWindow (nObject, nDx, nDy);

说明：使用SizeWindow函数来改变一个特定用户界面元件的大小。以像素点来指定新的

  大小。

参数：

nObject

指定要调整大小的对象。在该参数位置传递下列预定义的常量之一：

BACKGROUND：标识为主背景窗口。

METAFILE：标识为在文件传输过程中使用的布告牌。SizeWindow不支持位图文件（.bmp）。该参数对用SdBitmap函数显示的图元文件不起任何作用。SdBitmap自动调整被显示的图元文件的大小。

MMEDIA_AVI：设置播放下一个AVI文件的窗口的大小。所有AVI视频以一个缺省大小来显示。改变大小可能会改变视频的有效分辨率和明快度。

nDx

以像素点指定对象的水平大小。

nDy

以像素点指定对象的垂直大小。

返回值：

0：表明函数成功调整窗口大小。

< 0：表明函数未能调整窗口大小。

注解：

·安装程序可能运行于多个不同的屏幕分辨率下。因此，你需要使用GetExtents函数来确定屏幕的全屏大小，然后在你的SizeWindows函数调用中参数使用比率来指定用户界面对象的大小。

·该函数仅推荐给高级开发人员。

2.17  StatusUpdate

语法：StatusUpdate (bLink, nFinalPercent);

说明：StatusUpdate函数激活或禁用文件传输操作和状态条进度指示器之间的连接。当bLink是ON，连接被激活并且nFinalPercent指示一个在下一个文件传输结束时显示的最后百分比。在文件传输过程中，状态条平滑地从它的当前值更新到由nFinalPercent指定的值。当bLink是OFF，连接被禁用并且状态条的进度指示器在随后的文件传输中不会被自动更新。

如果文件传输中状态条被激活，则在每次调用CopyFile 或 XcopyFile之前调用StatusUpdate。在调用ComponentTransferData传输文件之前，带参数为ON和100来调用StatusUpdate；这将使状态条在安装的文件传输阶段平滑更新到100%。注意在一个运行基于事件脚本的安装中，ComponentTransferData被自动调用。

参数：

bLink

指定是否激活或禁用文件传输操作和状态条进度指示器之间的连接。在该参数位置传递下列预定义常量之一：

ON：指定状态条的进度指示器必须和文件传输操作相连接。

OFF：指定禁用状态条的进度指示器和文件传输操作之间的连接。连接保持为禁用直到它通过一个随后对StatusUpdate带参数bLink为ON的调用而得到重新建立。

状态条可以通过调用SetStatusWindow而被手动更新。

nFinalPercent

指定当bLink为ON时，状态条的进度指示器在下一个文件传输操作结束时必须达到的最后百分比。如果传递给nFinalPercent的值小于状态条的进度指示器的当前值，则进度指示器不会改变。当bLink为OFF时，该参数被忽略。

返回值：

0：表明函数成功。

< 0：表明函数不成功。

注解：

·该函数通过计算由任何文件传输函数传递的总的字节数来工作。然后它计算从进度指示器的当前位置开始到nFinalPercent中的最大值，需每隔多久增加一次进度指示器。

·StatusUpdate函数不能和VerUpdateFile 、VerSearchAndUpdateFile一起工作。当调用那些函数时，你必须禁用状态条或手动更新它。

·为设置状态条到一个初始百分比，在调用StatusUpdate之前调用SetStatusWindow。

3  信息函数

下列信息函数提供操作环境中有效资源的数据：磁盘空间，内存和操作模式：

s GetDiskSpace

返回指定磁盘的有效字节数（未使用的）（最高为2GB）。

s GetDiskSpaceEx

以bytes、kilebytes、megabytes或gigabytes为单位返回一个磁盘的空闲空间，。

s GetEnvVar

返回一个环境变量的当前值。

s GetExtents

返回屏幕大小。

s GetMemFree

返回运行在Microsoft Windows下的一个应用程序的可用内存。

s GetSystemInfo

检索系统信息。

s GetValidDrivesList

返回目标系统中所有有效驱动器。

s GetWindowHandle

返回主安装窗口的句柄。

s Is

提供文件和路径检查服务，查找一个数学协处理器，检测 Windows NT下的管理状态，确定Microsoft Windows是否从网络的共享版本运行。

3.1  GetDiskSpace

语法：GetDiskSpace (szDrive);

说明：GetDiskSpace函数返回指定驱动器上的空闲磁盘空间。

参数：

szDrive

指定一个驱动器指示符（驱动器字符后随一个冒号）。你也可在该参数位置指定一个通用导航计算机路径。

返回值：

XXXX：在指定驱动器上的空闲字节数。最大的返回值是2GB。超过2GB的空闲空间也返回2GB。当你需要检测超过2GB的空闲空间时需调用GetDiskSpaceEx。

< 0：表明GetDiskSpace未能获得空闲磁盘空间值。

3.2  GetDiskSpaceEx

语法：GetDiskSpaceEx (szDrive, nUnits);

说明：GetDiskSpaceEx函数返回指定驱动器的空闲磁盘空间值。传递给nUnits的值确定GetDiskSpaceEx的返回值是以bytes、 kilobytes、 megabytes 或 gigabytes度量。

参数：

szDrive

指定一个驱动器指示符（驱动器字符后随一个冒号）。用户也可在该参数位置指定一个通用导航计算机(UNC)路径。

nUnits

传递下列预定义常量之一来指明度量单位：

BYTES：指明GetDiskSpaceEx须返回空闲byte数。

KBYTES：指明GetDiskSpaceEx须返回空闲kilobyte数。

MBYTES：指明GetDiskSpaceEx须返回空闲megabyte数。

GBYTES：指明GetDiskSpaceEx须返回空闲gigabyte数。

返回值：

XXXX：在指定驱动器上的空闲bytes、kilobytes、megabytes或 gigabytes数，度量单位视nUnits值而定。

< 0：表明GetDiskSpaceEx未能获得空闲磁盘空间值。

3.3  GetEnvVar

语法：GetEnvVar (szParameter, svValue);

说明：GetEnvVar函数检索一个环境变量的当前值。

参数：

szParameter

指定其值要被检索的环境变量的名称。

svValue

返回该环境变量的当前值。

返回值：

0：表明函数检索到环境变量的值。

< 0：表明函数未能检索到环境变量的值。

注解：

·InstallShield没有提供一个改变一个环境变量值的机制。在Microsoft Windows 3.x  和 95环境中，建议用户不要改变环境变量值。如果用户需要设置一个新的环境变量，在Autoexec.bat文件中设置然后重启系统。对于Windows NT，查看如何在Windows NT下设置环境变量。

3.4  GetExtents

语法：GetExtents (nvDx, nvDy);

说明：GetExtents函数检索屏幕大小。屏幕宽以像素点为单位返回给nvDx，高以像素点为单位返回给nvDy。如：一个标准的VGA监控器返回nvDx为640，nvDy为480。

参数：

nvDx

以像素点为单位返回屏幕的宽。

nvDy

以像素点为单位返回屏幕的高。

返回值：

0：表明函数成功检索到屏幕的大小。

< 0：表明函数未能检索到这些值。

3.5  GetMemFree

语法：GetMemFree ( );

说明：GetMemFree函数返回运行在Microsoft Windows下的一个应用程序可用的内存大小。因为Microsoft Windows是一个虚拟内存系统，该函数不会返回实际物理内存（称为RAM）而是Windows应用程序可用的内存。要确定目标系统上可用的实际物理内存大小，可调用GetSystemInfo。

参数：

GetMemFree不带参数。以空参数表调用函数，如下所示：

   GetMemFree();

返回值：

XXXX：XXXX是应用程序可用的空闲内存的字节数。

< 0：GetMemFree未能返回空闲内存的大小。

注解：

·脚本每执行一个函数，InstallShield返回一个数值来指示函数运行结果。如果你要在该脚本后面部分要用到该函数的返回值，则将该值赋给一个数值型变量。

3.6  GetSystemInfo

语法：GetSystemInfo (nItem, nvResult, svResult);

说明：GetSystemInfo函数检索目标系统的信息。

参数：

第一个参数，nItem，用来指定要检索的信息的类型。参照下面这个你可传递给该参数的常量列表来检索系统信息。注意使用特定的常量时（如DISK_TOTALSPACE_EX），你必须在调用该函数前为参数nvResult和/或svResult指定附加信息。

系统信息返回给nvResult和/或svResult。数值型数据返回给nvResult。字符串型数据返回给svResult。下表列出了你可以传递给nItem的各个常量的返回值类型。

--------------------------------------------------------------------------------

nItem：BOOTUPDRIVE

nvResult：启动驱动器的 ID，1=A：，2=B：，3=C：。可以通过给该数值加上64（十进制）将该数字转换为相应的驱动器字符，然后给该值设置一个字符串变量。使用下面的语法进行转换：

svResult[0]=64+nvResult;

svResult：返回启动驱动器的驱动器指示符（驱动器字符后随一个冒号）。

--------------------------------------------------------------------------------

nItem：CDROM

nvResult： TRUE或FALSE指示CD ROM是否可用。

SvResult： N/A

--------------------------------------------------------------------------------

nItem： COLORS

nvResult：返回用户系统可用颜色数目。结果从对目标系统的视频驱动器检索而得，而不是从视频卡得到。如果该卡支持256色但驱动器只能处理16色，返回的颜色值是16。

svResult:：N/A

--------------------------------------------------------------------------------

nItem：CPU

nvResult：返回下列常量之一：

IS_UNKNOWN    用户CPU未知。

IS_386           用户有一个386处理器。

IS_486           用户有一个486处理器。

IS_PENTIUM     用户有一个PENTIUM 处理器。

IS_ALPHA        用户有一个ALPHA处理器。

SvResult： N/A

--------------------------------------------------------------------------------

nItem：   DATE

nvResult： N/A

svResult： svResult:当前系统时间格式为MM-DD-YYYY。在月和日域的首零被删除。

--------------------------------------------------------------------------------

nItem：   DISK_TOTALSPACE

nvResult:：返回由svResult指定的磁盘驱动器的总容量。最大返回值为2GB。总容量大于2GB的仍返回2GB。

SvResult：驱动器字符。注意该参数是传递给该函数的；也就是说，你必须在调用GetSystemInfo前给svResult赋值。还要注意你必须在驱动器字符后加上冒号；否则函数执行会失败。你也可以在该参数位置指定一个通用导航计算机（UNC）路径。

--------------------------------------------------------------------------------

nItem：   DISK_TOTALSPACE_EX

nvResult： 指定度量单位；在该参数位置传递下列预定义的常量之一：BYTES, KBYTES, MBYTES 或GBYTES。在svResult返回指定磁盘驱动器的总容量。

SvResult：驱动器字符。注意该参数是传递给该函数的；也就是说，用户必须在调用GetSystemInfo前给svResult赋值。还要注意必须在驱动器字符后加上冒号；否则函数执行会失败。用户也可以在该参数位置指定一个通用导航计算机（UNC）路径。

--------------------------------------------------------------------------------

nItem：   DRIVE

nvResult:：在svResult返回指定驱动器的类型。将返回下列常量之一：

IS_UNKNOWN -目标驱动器未知。

IS_REMOVABLE -目标驱动器是软盘驱动器。

IS_FIXED -目标驱动器是硬盘驱动器。

IS_CDROM -目标驱动器是光盘驱动器。

IS_REMOTE -目标驱动器是一网络驱动器。

SvResult：驱动器字符后随冒号。注意该参数是传递给该函数的；也就是说，用户必须在调用GetSystemInfo前给svResult赋值。用户也可以在该参数位置指定一个通用导航计算机（UNC）路径。

--------------------------------------------------------------------------------

nItem：   EXTENDEDMEMORY

nvResult： NvResult:返回安装在机器上的内存大小。由于操作系统的限制，返回值可能会和安装在机器上的实际物理内存大小稍有差异。该值通常比实际值小100K。注意返回值以kb来度量。

SvResult： N/A

--------------------------------------------------------------------------------

nItem：    LANGUAGE

nvResult： nvResult:该参数返回目标系统的InstallShield语言常量。返回的常量可以用来确定使用ComponentFilterLanguage函数的安装中装入哪些语言专用文件组。

 For information about determining the default language of the target system, click here. 

InstallShield International支持21种语言，Windows支持100多种语言。如果你想根据nvResult值筛选文件组，则必须使用一个开关语句根据该函数的返回常量来确定要使用的InstallShield语言标识号常量。带该参数时该函数的性能高度依赖于系统。

SvResult：该参数返回和nvResutl返回的语言常量等价的语言名称字符串。

--------------------------------------------------------------------------------

nItem：OS

nvResult：返回目标操作系统平台。返回下列常量之一：

IS_WINDOWSNT -  操作系统是Windows NT。

IS_WINDOWS9X -  操作系统是Windows 95或Windows 98。为确定是哪个，带WINMINOR调用GetSystemInfo来检测监控器版本。如果小于10，则操作系统是Windows 95；否则是Windows 98。

SvResult：N/A

--------------------------------------------------------------------------------

nItem：   PARALLEL

nvResult： 返回有效的物理并行口数目。

SvResult： N/A

--------------------------------------------------------------------------------

nItem：   SERIAL

nvResult： 返回有效的物理串行口数目。

SvResult： N/A

--------------------------------------------------------------------------------

nItem：   TIME

nvResult： N/A

svResult： 以HH:MM:SS格式返回当前系统时间。

--------------------------------------------------------------------------------

nItem： VIDEO

nvResult：nvResult:返回安装的视频适配器类型。（InstallShield不能检测CGA或单色视频驱动器）。返回下列常量之一：

IS_UNKNOWN -未知的用户视频适配器。

IS_EGA - EEGA分辨率。

IS_VGA - VGA分辨率。

IS_SVGA - SVGA（800×600）分辨率。

IS_XVGA - XVGA（1024×768）分辨率。

IS_UVGA -大于1024×768分辨率。

SvResult：N/A

--------------------------------------------------------------------------------

nItem：   VOLUMELABEL

nvResult： N/A

svResult： 传递你要检索其卷标号的驱动器的驱动器指示符（驱动器字符后随冒号）。该参数返回指定的驱动器的卷标号。如果该驱动器没有卷标号，返回空字符串。

--------------------------------------------------------------------------------

nItem：  WINMAJOR

nvResult：返回Windows的主版本号。

SvResult：以##.###格式返回一个字符串，指明Windows的主、次版本号。

--------------------------------------------------------------------------------

nItem：  WINMINOR

nvResult：返回Windows的次版本号。

SvResult：以##.###格式返回一个字符串，指明Windows的主、次版本号。

--------------------------------------------------------------------------------

返回值：

0：表明函数成功返回指定信息。

< 0：表明函数未能返回指定信息。

3.7  GetValidDrivesList

语法：GetValidDrivesList (listID, nDriveType, nMinDriveSpace);

说明：GetValidDrivesList函数检索目标系统的符合特定条件的所有驱动器列表。这个条件包括驱动器类型和驱动器的最小空间数。如果一个驱动器未关闭，该驱动器名仍加入列表。

你可以在驱动器罗列之前指定要查找的驱动器的类型（nDriveType）和可用的最小磁盘空间（nMinDriveSpace）。

参数：

listID

返回有效驱动器字符的一个列表。由listID标识的字符串列表必须通过对ListCreat的调用已被初始化。

nDriveType

指定要查找的驱动器的类型。在该参数位置传递下列预定义的常量之一：

-1：查找所有驱动器类型。

FIXED_DRIVE：仅查找硬盘驱动器。

REMOTE_DRIVE：仅查找远程驱动器。远程驱动器通常位于网络。

REMOVEABLE_DRIVE：仅查找可卸式驱动器。软盘驱动器是可卸式驱动器。

CDROM_DRIVE：仅查找光盘驱动器。

nMinDriveSpace

指定包括在返回列表中的驱动器所必须有的最小的空闲磁盘空间的字节数。如果nMinDriveSpace小于0，GetValidDrivesList将不检测驱动器的最小空间。这对软盘驱动器有用。

返回值：

0：函数成功检索所要求的列表。

< 0：函数未能检索到要求的序列。

注解：

·网络映射驱动器也可作为远程驱动器返回。该函数不会返回所有网络上的驱动器，仅返回那些标识为映射驱动器的驱动器。

3.8  GetWindowHandle

语法：GetWindowHandle (nHwndFlag);

说明：GetWindowHandle函数得到安装主窗口的句柄。

参数：

nHwndFlag

指定InstallShield主窗口的窗口句柄。在该参数位置传递预定义的常量HWND_INSTALL。 

返回值：

X：X是窗口句柄。

< 0：函数未能检索到句柄。

3.9  Is

语法：Is (nIsFlag, szIsData);

说明：Is函数检索脚本中需要的公用信息。

参数：

nIsFlag

指定要检索的信息类型。在该参数位置传递下列预定义的常量之一：

DIR_WRITEABLE：能否写到由szIsData指定的目录？

FILE_EXISTS：由szIsData指定的文件是否存在？

FILE_LOCKED：文件是否锁定？

FILE_WRITEABLE：能否写到由szIsData指定的文件？

MATH_COPROCESSOR：在目标系统是否存在一个数学协处理器？

PATH_EXISTS：由szIsData 指定的路径是否存在？

USER_ADMINISTRATOR：当目标操作系统是Windows NT时，当前用户是否拥有管理员特权？运行于Windows 95或更高版本下的安装程序，Is通常在参数nFlag为 USER_ADMINISTRATOR时返回TRUE

VALID_PATH：由szIsData指定的路径是否一个合法路径？它不确认路径的存在与否，而仅检测它的语法。当你检索从用户处得到的路径信息时可以使用该常量。然后该函数会检测输入的路径信息是否正确。

WINDOWS_SHARED：Microsoft Windows是否从一个网络运行共享版本？

szIsData

指定信息，该信息依赖于传递给nIsFlag的常量，如下所示：

若nIsFlag是DIR_WRITEABLE,szIsData指定要被检测的全限定路径。

若nIsFlag是FILE_EXISTS,szIsData指定全限定文件名。

若nIsFlag是FILE_LOCKED，szIsData指定全限定文件名。

若nIsFlag是FILE_WRITEABLE，szIsData指定全限定文件名。

若nIsFlag是MATH_COPROCESSOR，szIsData指定的内容被忽略。

若nIsFlag是PATH_EXISTS，szIsData指定全限定路径。 

若nIsFlag是USER_ADMINISTRATOR，szIsData被忽略。

若nIsFlag是VALID_PATH，szIsData指定全限定路径。

若nIsFlag是WINDOWS_SHARED，szIsData被忽略。

返回值：

TRUE (1)：表明答复为真。

FALSE (0)：表明答复为假。

< 0：函数未能答复问题。

注解：

·常量WINDOWS_SHARED仅能应用于Microsoft Windows版本。一个Microsoft Windows的共享版本安装于网络且有可被许多用户共享的公用文件。

4  内部对话框函数

   下列函数创建简单对话框，如Yes/No对话框和消息框。一些函数允许你简单地显示公用对话框的各种类型。

有Cancel按扭的内部对话框当该按扭被选中时不返回CANCEL(2)值。而是调用当前定义的退出处理程序。

注意：作为缺省，InstallShield  Professional 6以Windows 2000 风格显示最终用户对话框，该风格遵照Windows用户界面的Microsoft的最新准则。为相应显示Windows 95风格的对话框，用户需做下列工作：

s 通过重命名或移至其它文件夹，将<InstallShield Professional 6文件夹>、Redistributable\Compressed Files\0009-English\Intel 32\_isres.dll备份。

s 将文件_isres.old 从<InstallShield Professional 6 文件夹>\Program\Migration\0009-English\Intel 32拷贝至<InstallShield Professional 6 文件夹>\Redistributable\compressed Files\0009-English\Intel 32。

s 改变文件名_isres.old为isres.dll。

s 单击建立工具栏Build toolbar'的建立当前媒体按钮Build Current Media或从建立菜单选择建立<媒体名称>媒体来建立用户的媒体。

具体函数包括以下这些：

s AskDestPath

显示一个要求目标路径信息的对话框。

s AskOptions

显示一个对话框，提示最终用户通过复选框或单选钮来选择选项。

s AskPath

显示提示最终用户输入一个路径的对话框。

s AskText

显示提示最终用户输入文本的对话框。

s AskYesNo

显示一个对话框，提示最终用户通过点击Yes或No按扭来响应问题。

s ComponentDialog

显示一个对话框，让最终用户选择组件和指定一个目标位置。

s EnterDisk

显示一个对话框，提示最终用户一个指定的磁盘。

s MessageBox

在对话框中显示一条信息。

s RebootDialog

显示一个对话框，使最终用户可以选择重启Windows或重启计算机。

s SelectDir

显示一个对话框，允许最终用户选择一个文件夹。当文件夹不存在时SelectDir创建该文件夹。

s SelectDirEx

显示一个对话框，允许最终用户选择一个文件夹。

s SelectFolder

显示一个对话框，允许最终用户从程序文件夹列表中选择一个文件夹。

s SetupType

显示一个对话框，允许最终用户选择典型、简易、自定义安装。

s SprintfBox

返回一个由一个或多个字符、数字或字符串值组成的格式化的字符串。

s Welcome

显示欢迎信息的对话框。

4.1  AskDestPath

语法：AskDestPath (szTitle, szMsg, svDir, nReserved);

说明：AskDestPath函数显示一个对话框，允许最终用户指定安装中文件安装到的目标文件夹。对话框还包括一个浏览按扭，允许最终用户选择一个存在的文件夹或指定一个新的文件夹。注意最终用户选择的文件夹必须可写；不可写的文件夹不被接受。如果你希望最终用户可以选择不可写的文件夹，可调用AskPath函数。

    为从选择目标位置对话框中打开选择文件夹对话框，最终用户必须点击浏览(Browse)按钮。选择文件夹对话框显示所有有效文件夹列表。最终用户可选择一个存在的文件夹或者输入一个新的文件夹名。如果最终用户输入一个不存在的文件夹名，该文件夹被创建。

参数：

szTitle

指定对话框标题。为显示缺省标题（“选择目标位置”），传递一个空字符串给该参数。

szMsg

指定要显示的消息。为在该参数传递多行静态文字，在行需要间断处插入新行转换符序列（\n）。为显示该对话框的缺省指令，传递空字符串（””）给该参数。

svDir

指定打开对话框时显示的缺省路径；返回到达最终用户选择的文件夹的路径。更多信息请看下面的注解。

nReserved

该参数的值必须是0。

返回值：

NEXT (1)：表明Next按钮被选中。

BACK (12)：表明Back按钮被选中。

注解：

·如果由svDir指定的缺省文件夹不存在于最终用户系统中，它不会被创建，除非最终用户按下选择按钮并且从选择文件夹对话框中按步骤创建它。因此，当用户指定一个希望在调用ComponentTransferData(它在必要时会创建文件夹)前使用的缺省文件夹时，用户必须在AskDestPath返回时调用ExistDir以此来确定文件夹是否存在。如果它不存在，调用CreatDir来在最终用户系统中创建它。注意一个运行基于事件的脚本的安装程序会自动调用ComponentTransferData。

· 运行在静止方式（silent mode）的安装程序，若缺省文件夹不存在，则必须在调用AskDestPath前创建它。

4.2  AskOptions

语法：AskOptions (nValue, szMsg, szText1, bvCheck1, szText2, bvCheck2[, szTextn, bvCheckn] [,..., ]);

说明：AskOptiona 函数格式化并显示提示最终用户选择一个或多个选项的对话框。对话框的缺省标题是“选择组件”。为改变标题栏的内容，在调用AskOptions前调用SetDialogTitle。该对话框将显示多至九个选择控件，复选框或单选钮，根据nValue的值而定。

参数：

nValue

指定要显示的控件。在该参数位置传递下列预定义常量之一：

EXCLUSIVE：指定单选按钮，允许最终用户仅选择一个选项。

NONEXCLUSIVE：指定复选框，允许最终用户选择一个以上的选项。

szMsg

指定在对话框显示的消息。你可以使用该消息来描述选项和/或要求最终用户选择一个或多个选项。如果消息多于一行，使用换行符（\n）插入行的间隔处。

szText1

指定一个最多达47个字母的文本标签，它相邻显示于第一个复选框或单选钮。为建立一个快捷键，在用户为该目的指定的字母前插入一个“与符号”（&）。该字母带下划线显示来指示它的功能。例如，自定义Alt+C为快捷键，传递“&Custom”。自定义Alt+S为快捷键，传递”Cu&stom”。

bvCheck1

指定对话框打开时第一个选择框或单选钮的初始状态；对话框关闭时返回第一个选择框或单选钮的状态。在该参数位置传递下列常量：

TRUE：第一个选择框或单选钮被选。

FALSE：第一个选择框或单选钮未被选中。

szText2

指定相邻显示于第二个选择框/单选钮的最多达47个字母的文本标签。创建一个快捷键的方法同szText1处。

bvCheck2

指定对话框打开时第二个选择框或单选钮的初始状态；对话框关闭时返回第二个选择框或单选钮的状态。在该参数位置传递下列常量：

TRUE：第二个选择框或单选钮被选。

FALSE：第二个选择框或单选钮未被选。

    可以定义多达七个附加选项。每个附加选项由一对参数指示：一个字符串参数定义一个标签和一个数值型变量定义AskOptions返回时的选项状态。为设置一个选项的初始状态，在调用AskOptions前给数值型变量赋值为TRUE 或FALSE。

    若nValue是EXCLUSIVE并且一个以上的选项设置的初始状态设置为TRUE，AskOptions将预选设置为TRUE的参数序列的第一个选项。

返回值：

NEXT (1)：表明Next按钮被选。控件的状态由各个bvCheck变量返回。

BACK (12)：表明Back按钮被选。控制的状态由各个bvCheck变量返回。

4.3  AskPath

语法：AskPath (szMsg, szDefPath, svResultPath);

说明：AskPath函数指定一个对话框，提示最终用户输入目标位置的路径。对话框包括一个单行编辑区，你可以在此显示一个缺省路径。最终用户有三个选择：

s 接受缺省路径

s 编辑缺省路径

s 显示选择文件夹Choose Folder对话框来选择一个文件夹

　　对话的缺省标题是选择目标位置Choose Destination Location。为改变该标题，在调用AskPath前调用SetDialogTitle。AskPath不检验最终用户输入路径的存在性。调用AskPath后调用CreatDir来创建该路径。

参数：

szMsg

指定显示在对话框中的消息。要显示该对话框的缺省指示，传递空字符串(“”)给该参数。

szDefPath

指定在编辑区显示的缺省路径。最终用户可以修改该字符串。

svResultPath

返回结果路径名，不管用户是否接受缺省路径，修改它，还是从选择文件夹Choose Folder对话框选择可选路径。AskPath在路径结尾加一个反斜杠，然后才把它赋给svResultPath。若必要，可在AskPath返回后通过调用StrResultPath 来删除反斜杠。如果用户按下返回按钮，svResultPath的值将不可预测。因此，如果用户在szDefPath和svResultPath使用相同的变量，那么确保当AskPath的返回值为BACK时重初始化该变量。

返回值：

NEXT (1)：表明最终用户选择Next按钮。

BACK (12)：表明最终用户选择Back按钮；svResultPath设置为空字符串(“”)。

注解：

·在对话框显示的编辑区可滚动以适应长字符串。

·因为可以输入至编辑区的字符数目不受限制，所以用户必须以不定长来说明svResultPath传递的变量。如果字符串变量不足以存储用户输入的文本，字符串将被截尾并且显示错误信息。同样要注意既然这个函数在字符串结尾附加一个反斜杠和一个空结束符，字符串的长度至少比用户输入的路径长两个字符。

·该函数将接受一个存在但不可写的文件夹。为限制最终用户只可选择可写的文件夹，可调用AskDestPath函数来替代。

4.4  AskText

语法：AskText (szQuestion, szDefault, svResult);

说明：AskText函数显示一个对话框，它包括一个静态文本区和一个编辑框。参数szQuestion指定静态文本区的缺省文本；参数szDefault指定编辑框的缺省文本。该对话框的缺省标题是输入信息Enter Information。为改变标题栏的内容，在调用AskText前调用SetDialogTitle。

参数：

szQuestion

指定要显示的问题或声明。如果该参数位置的字符串长度超过静态文本区宽度，一个或多个行分隔符将会被插入该字符串使得它在对话框多行显示。如果愿意，用户也可以自己通过插入换行符（\n）手动格式化该字符串。该参数没有一个缺省值。

szDefault

指定编辑区的缺省文本。

svResult

当Next按钮被用来关闭对话框时返回由最终用户输入的文本。如果用户按下Back按钮，svResult值将不可预测。因此，如果用户在szDefPath和svResultPath使用相同的变量，那么需确保当AskPath的返回值为BACK时重初始化该变量。

返回值：

NEXT (1)：表明Next按钮被按下。

BACK (12)：表明Back按钮被按下。

注解：

·用户在svResult传递的字符串变量必须足够大以适应输入到编辑区的文本。因此，用户必须使用自动调节大小的方法来声明变量。

·必要时，编辑区将会滚动来以适应一个长字符串。

4.5  AskYesNo

语法：AskYesNo (szQuestion, nDefault);

说明：AskYesNo函数呈现一个消息框，显示一个问题，最终用户可以通过单击Yes或No按钮来回答它。AskYesNo消息包含四个内容：

．问题标记图标　　．问题文本　　．Yes按钮　　．No按钮

　　缺省标题是Question。为改变标题栏的内容，在调用AskYesNo前调用SetDialogTitle。

AskYesNo消息框由直接调用相应的Windows API函数创建,它显示一个系统模态对话框。由于该对话框是由Windows显示的，按钮上的文本不能由安装改变。英语版本的文本’Yes’或’No’将由Windows 以适合运行安装的Windows版本的语言显示。如果用户需要显示另一个柔性对话框，直接调用一个Windows API函数或使用一个自定义对话框。

参数：

szQuestion

指定显示在消息框中的问题。如果消息超过一行，在消息中嵌入换行符(\n)来插入行间隔。

nDefault

指定缺省选定的按钮。在该参数位置传递下列预定义的常量之一：

YES：当对话框打开时Yes 按钮高亮显示。

NO：当对话框打开时No按钮高亮显示。

返回值：

YES (1)：表明用户选择Yes 按钮。

NO (0)：表明用户选择No按钮。

4.6  ComponentDialog

语法：ComponentDialog (szTitle, szMsg, svDir, szComponent);

说明：ComponentDialog函数显示一个对话框，允许最终用户从当前媒体上的组件列表中选择一项或多项。用户也可以选择一个目标位置。

    如果你的安装不使用一个安装类型对话，用户必须在调用ComponentDialog前调用ComponentTypeSet来指定一个已经在IDE安装类型窗格中定义的安装类型。

    当前媒体的名称存储在系统变量MEDIA中。在安装初始化过程中，InstallShield给MEDIA赋值为缺省媒体名称(“DATA”)，它和用户文件媒体库（Data1.cab）相联系。显示脚本创建的组件时，按下列步骤进行：

s 保存MEDIA的当前值

s 将脚本创建组件组的名称赋给MEDIA

s 调用ComponentDialog得到最终用户的选择

s 将步骤1的值赋给MEDIA

    在安装初始化中系统变量MEDIA的值设置为’DATA’。如果用户改变该变量的值来引用脚本创建的组件组，用户必须在调用ComponentTransferData， CreateShellObjects 或CreateRegistrySet前将值改回’DATA’。注意在一个基于事件的脚本的安装中ComponentTransferData被自动调用。

    单击浏览按钮装入选择文件夹Choose Folder对话框，显示存在的文件夹列表。最终用户可以选择一个存在的文件夹或输入一个新的文件夹名称。ComponentDialog在svDir返回被选的文件夹名称。

如果用户输入一个不存在的文件夹，将出现一个消息框来询问最终用户是否要创建这个文件夹。如果是，则InstallShield创建指定的文件夹。

参数：

szTitle

指定对话框标题。为显示缺省标题（“选择组件Select Components”）， 给该参数传递一个空字符串（””）。

szMsg

指定在对话框显示的消息。例如，消息可能为“请选择一个或多个下列组件安装在你的系统上” "Please select one or more of the following components to install on your system."。为显示该对话框的缺省指示，给该参数传递一个空字符串（””）。

svDir

指定缺省目标位置。返回最终用户选择的文件夹。注意在svDir 返回的位置值不影响文件传输除非用户将它赋值给系统变量TARGETDIR或调用ComponentSetTarget来将它和一个用户定义的变量联系起来。

    我们建议用户给该参数传递TARGETDIR而不是一个字符串变量。如果你在该参数不传递TARGETDIR，当最终用户在一个不同驱动器选择一个目标时显示在对话框的所需磁盘空间不会被重算。

szComponent

指定组件，其子部件被显示以供选择。给该参数传递一个空字符串（””）来显示所有顶层组件。

ComponentDialog在文件媒体库或脚本创建的组件组中查找由系统变量MEDIA指定的所需组件。

返回值：

NEXT (1)：表明最终用户选择Next按钮。

BACK (12)：表明最终用户选择Back按钮。

< 0：未能显示ComponentDialog对话框。调用ComponentError查看附加信息。

注解：

·组件大小显示为0直到它被选中。一旦它被选中，它的实际大小被显示。

·若有必要，组件名称被截尾来显示最大可能的组件大小。显示大小的必要空间依赖于组件最大大小本身（2GB），当前使用的组件大小选项，和用来在对话框显示组件信息的字体。组件大小选项由DialogSetInfo函数设置。一旦显示最大可能大小所需的空间被确定，若有必要，所有组件名均被截尾以适应剩余空间。这确保组件名不会覆盖组件大小。注意，在这种方法下需要较少空间显示大小（或没有被选）的组件的名称仍然会被截尾。为了最大化执行并确保组件名称完整显示，使组件名小于在组件对话框中的有效空间。

·如果由svDir指定的缺省文件夹不存在于最终用户系统，它不会被创建除非最终用户按下浏览按钮并按下列步骤从选择文件夹对话框创建它。因此，无论何时用户想在调用ComponentTransferData(必要时，它会创建文件夹)前指定一个要使用的缺省文件夹，为了确定该文件夹是否存在，当ComponentDialog返回时都必须调用ExistDir 。如果不存在，调用CreatDir在最终用户系统上创建它。

·运行在静止方式的安装如果在调用ComponentDialog前文件夹不存在必须创建该新文件夹。这样可以确保确认对话框不被显示。没有这一步，需要两个响应文件来处理两个可能情况。

4.7  EnterDisk

语法：EnterDisk (szMsg, szTagFile);

说明：EnterDisk函数显示一个对话框，提示最终用户插入下一张磁盘。缺省标题是安装需要下一张磁盘。为改变该标题，在调用EnterDisk前调用SetDialogTitle。系统变量SRCDIR包含缺省路径，该路径显示在对话框中。最终用户可以修改缺省路径并通过输入一个新路径和单击OK来修改SRCDIR值。

    EnterDisk通过在磁盘查找由szTagFile指定的标签文件识别正确磁盘。如果磁盘不包含标签文件，会有一个错误消息提示用户输入正确磁盘。

参数：

szMsg

指定提示用户插入正确磁盘的消息。

szTagFile

指定标签文件名。EnterDisk在插入磁盘上查找该文件。如果文件没有找到，会显示一个消息要求用户插入正确的磁盘。如果用户给该参数传递一个空字符串(“”)，函数不查找任何文件；而是假定安装了正确的软盘。

返回值：

OK (1)：表明用户选择了OK按钮。

< 0：表明发生了一个未确定错误。

注解：

·InstallShield媒体生成器不会自动在磁盘映像文件夹上生成标签文件。为使用标签文件，将它们加到创建好的磁盘映像文件夹中。

4.8  MessageBox

语法：MessageBox (szMsg, nType);

说明：MessageBox函数呈现一个对话框，包含一个消息，一个指示消息自然属性的图标（信息，警告，或严重警告），和一个OK按钮。缺省标题依赖于nType值，nType值也指示图标类型。为改变消息框标题栏的内容，在调用MessageBox前调用SetDialogTitle。

参数：

szMsg

指定要显示的消息。InstallShield不会自动分隔消息文本为单独的行来适应消息框。如果消息长于一行，通过在字符串的合适位置嵌入换行符(\n)来插入行间隔。

nType

指定要创建的消息框类型和显示在消息框的图标类型。在该参数位置传递下列预定义的常量之一（显示资源管理器对象处理程序图标）：

   INFORMATION   WARNING   SEVERE

任何Windows API MessageBox类型也可在该参数指定。多种风格可以被逻辑或来产生所需的MessageBox类型（请看下面的注解）。

返回值：

    除非你使用标准Microsoft Windows 消息框风格，返回值没有意义。如果你使用这些风格，返回值和MessageBox API函数的返回值一样。

注解：

·该函数使用Microsoft Windows API MessageBox。操作环境，而不是InstallShield，确定消息框的大小和位置（例如，操作系统运行所在的语言）。你可以改变该按钮的文本。考虑使用Windows MessageBox类型的更多信息，请在适当的Windows SDK中咨询MessageBox Windows API 函数的描述。

·当使用Windows 消息框常量时注意下列情况：

·Windows MessageBox 类型常量在Windows.h文件中声明，它不能包括在InstallShield 脚本中。当使用这些常量，用户必须在安装脚本的声明区定义它们（使用#define）。赋给这些常量的值通常可在一个适当的Windows SDK或开发工具提供的包含文件中找到。对于Microsoft Visual C++，大多数常量可在 Winuser.h文件中找到，它位于DevStudio\Vc\include 文件夹。

·Windows 和InstallShield消息框常量不能在一个安装中一起使用。如果一个InstallShield消息框常量和一个 Windows 消息框常量用一个或运算符组合，Windows 消息框常量将被忽略。

·一些Windows 消息框风格在一些Windows 平台不受支持。为确定一个特定的风格是否受安装确定的操作系统支持，咨询适当的Windows SDK。

·当MessageBox函数使用一个Windows 消息框风格时，消息框的标题是“安装“。如果用户需要显示不同的标题，可使用SprintfBox函数来替代。

4.9  RebootDialog

语法：RebootDialog (szTitle, szMsg, nDefChoice);

说明：RebootDialog函数显示一个对话框,允许最终用户重启计算机。被选的选项在安装的最后被执行。

参数：

szTitle

指定对话框标题。为显示缺省标题（“重新启动”），给该参数传递一个空字符串(“”)。

szMsg

指定对话框显示的消息。为显示该对话框的缺省指示，给该参数传递一个空字符串(“”)。

nDefChoice

指定缺省选定的单选钮内容。在该参数位置传递下列预定义常量之一：

SYS_BOOTMACHINE：重启计算机选项("Yes, I want to restart my computer now.")将成为缺省单选按钮选定内容。

0：不重启计算机选项("No, I will restart my computer later.")将成为缺省单选按钮内容。

返回值：

WILL_REBOOT：表明用户选择标签为"Yes, I want to restart my computer now."的单选钮。

0：表明用户选择标签为"No, I will restart my computer later."的单选钮。

注解：

·当你带SHAREDFILE或LOCKEDFILE选项来调用一个函数并且锁定遇到的.dll或.exe文件，锁定的文件的更新版本被拷贝至目标系统并且系统变量BATCH_INSTALL设置为TRUE。RebootDialog当系统重启时自动提交被锁定的文件以更新，除非用户选择"No, I will restart my computer later."选项。

·RebootDialog函数的一个完美候选是SdFinishReboot，它比RebootDialog对话框一个更好的外观和感觉。

·因为当InstallShield的其它实例运行时InstallShield会尽力不重启系统，所以用户必须确保所有其它InstallShield的实例在调用RebootDialog前停止执行。另外，你给用户的消息需要求他们确保在重启系统前所有其它应用程序停止执行。

4.10  SelectDir

语法：SelectDir (szTitle, szMsg, svDir, bCreate);

说明：SelectDir函数显示一个对话框，允许最终用户指定应用程序将被安装到的文件夹。最终用户可以输入一个全限定文件夹名或从列表中选择一个存在的文件夹。如果最终用户输入一个无效文件夹名或一个未限定文件夹名，将显示一个消息框提示最终用户输入一个有效名。选择文件夹的全限定名返回给svDir。

    如果指定的文件夹不存在并且参数bCreate是TRUE，显示一个消息框询问是否要创建文件夹。如果最终用户单击Yes, SelectDir自动创建指定的文件夹。如果参数bCreate设置为FALSE并且一个不存在的文件夹被选中，最终用户不会被告之，并且SelectDir不创建它。这种情况下，该由用户处理包含在svDir的选项。

    当最终用户单击呈现在由AskDestPath, SdAskDestPath 和其它获得一个文件夹名的InstallShield函数显示的对话框中的Browse按钮时SelectDir 被自动调用。

参数：

szTitle

指定对话框标题。为显示缺省标题（“选择文件夹”），给该参数传递一个空字符串（””）。

szMsg

指定用户要在该对话框显示的消息。为显示该对话框的缺省指示，给该参数传递一个空字符串(“”)。

svDir

指定将作为缺省选项显示的文件夹名。返回由最终用户选定的文件夹的全限定名。

bCreate

指定你是否要求InstallShield在指定文件夹不存在时创建它。在该参数位置传递下列预定义常量之一：

TRUE：表明如果文件夹不存在则需被创建。

FALSE：表明如果文件夹不存在不需被创建。

返回值：

IDOK (1)：表明OK按钮被按下。

IDCANCEL (2)：表明CANCEL按钮被按下。

< 0：表明该函数未能显示对话框并/或不能创建文件夹。

4.11  SelectDirEx

语法：SelectDirEx (szTitle, szMsg, szEditBoxStaticText, szTreeControlStaticText, nFlags, svDir);

说明：SelectDirEx显示一个对话框，允许最终用户从一个显示存在文件夹的树形控件中选择一个存在的文件夹。也显示一个编辑框，允许最终用户指定一个新文件夹。

    该函数调用Windows API函数SHBrowserForFolder来显示对话框。为得到SHBrowseForFolder更多信息，可查看Win32 SDK或访问http://msdn.microsoft.com/library/ sdkdoc/ shellcc/shell/Function s/SHBrowseForFolder.htm.

参数：

szTitle

指定对话框标题。为显示缺省标题（“选择文件夹”），给该参数传递一个空字符串（””）。

szMsg

指定用户要在该对话框显示的消息。为显示该对话框的缺省指示（“请选择安装文件夹”），给该参数传递一个空字符串(“”)。

szEditBoxStaticText

当nFlags 为BIF_EDITBOX时指定伴随编辑框的静态文本。如果nFlag不指定BIF_EDITBOX，该参数被忽略。

szTreeControlStaticText

当nFlags 指定BIF_STATUSTEXT时，指定伴随对话框的树形控件的静态文本。如果nFlags不指定BIF_STATUSTEXT，该参数被忽略。

nFlags

指定函数显示的对话框的外观和功能。传递任何下列常量：

BIF_BROWSEFORCOMPUTER：允许最终用户选择网络上的一特定计算机。当传递该常量时，对话框有如下行为（性能）：

s “网络邻居”文件夹在树形控件中被预选。

s 仅当选中树形控件中的一个有效计算机名时，OK按钮被激活。

s 即使BIF_EDITBOX指定时也不显示编辑框。

BIF_BROWSEFORPRINTER：允许最终用户选择一特定打印机。当传递该常量时，对话框有如下行为：

s “网络邻居”文件夹在树形控件中被预选。

s 仅那些包括至少一台打印机的计算机在网络邻居文件夹中显示。

s 仅当选中树形控件中的一个有效打印机时，OK按钮被激活。

s 即使BIF_EDITBOX指定时也不显示编辑框。

BIF_DONTGOBELOWDOMAIN：域层下的网络文件夹不在树形控件中显示。

BIF_RETURNFSANCESTORS：如果一个文件系统祖先以外的任何对象被选中时OK按钮被禁用。

BIF_RETURNONLYFSDIRS：非文件系统某部分的一个文件夹被选中OK按钮被禁用。.

下列常量指定对话框的其它特征：

BIF_EDITBOX：显示一个编辑框，允许用户输入一文件夹名，在编辑框上部显示szEditBoxStaticText中的文本（除非指定BIF_BROWSEFORCOMPUTER 或BIF_BROWSEFORPRINTER）。当最终用户单击OK，SelectDirEx检查是否输入了一个有效文件夹名。如果不是（例如，如果输入了包含无效字符的名称），显示一个错误消息并且对话框不被消除。和SHBrowseForFolder不同，SelectDirEx对所有InstallShield支持的操作系统都支持该常量。

BIF_STATUSTEXT：在树形控件上部作为态文本显示szTreeControlStaticText。注意SelectDirEx不支持BIF_VALIDATE 和 BIF_USENEWUI常量，而SHBrowseForFolder支持它们。

svDir

指定作为缺省选择出现的文件夹名。返回由最终用户选择的文件夹的全限定名。如果该参数指定了一个存在于系统的有效文件夹名，该文件夹在树形控件中被预选。

返回值：

IDOK (1)：表明OK按钮被按下。

IDCANCEL (2)：表明CANCEL按钮被按下。

< 0：表明函数未能显示对话框。

4.12  SelectFolder

语法：SelectFolder (szTitle, szDefFolder, svResultFolder);

说明：SelectFolder函数显示一个对话框，允许最终用户在一个编辑区输入一个程序文件夹名或从一个列表中选择一个程序文件夹。该函数自动显示系统中所有的程序文件夹。SvDefFolder传递的一个缺省的文件夹名在编辑区显示。在svResultFolder返回被选的文件夹名。如果指定文件夹不存在，它不会被创建。

参数：

szTitle

指定对话框标题。为显示缺省标题（“选择程序文件夹”），给该参数传递一个空字符串（””）。

szDefFolder

指定作为缺省文件夹显示的文件夹名。

svResultFolder

返回由最终用户选中或指定的文件夹名。如果文件夹不存在，你必须调用CreateProgramFolder来创建它；SelectFolder不会创建该文件夹。

返回值：

NEXT (1)：表明最终用户选择Next按钮。

BACK (12)：表明最终用户选择Back按钮。

< 0：表明函数未能成功执行。

4.13  SetupType

语法：SetupType (szTitle, szMsg, szReserved, nType, nReserved);

说明：SetupType函数显示一个对话框允许最终用户选择三种标准安装类型之一。典型、简易或自定义。这些安装选项显示时有标准描述文本。如果你想加入其它安装类型或改变显示的安装类型名或描述，可调用SdSetupTypeEx。

    如果最终用户在使用组件对话框来选定和撤消选定与已选安装类型相联系的组件后，返回到安装类型对话框，那么那些选择将丢失。这种情况发生是因为SetupType函数每次被调用时自动根据选中的安装类型复位缺省组件选项。

参数：

szTitle

指定对话框标题。为显示缺省标题（“安装类型”） ，给该参数传递一个空字符串（””）。

szMsg

指定你要在对话框顶部显示的消息。为显示该对话框的缺省指示，给该参数传递一个空字符串（””）。

szReserved

给该参数传递一个空字符串(“”)，不允许其它值。

nType

当对话框打开时指定缺省安装类型。在该参数位置传递下列预定义常量之一：

TYPICAL：定义缺省安装类型为典型。

COMPACT：定义缺省安装类型为简易。

CUSTOM：定义缺省安装类型为自定义。

nReserved

给该参数传递0，不允许其它值。

返回值：

TYPICAL (301)：表明选择了典型安装类型。

COMPACT (302)：表明选择了简易安装类型。

CUSTOM (303)：表明选择了自定义安装类型。

BACK (12)：表明选定了Back按钮。

4.14  SprintfBox

语法：SprintfBox (nType, szTitle, szFormat [,arg] [,...]);

说明：SprintfBox函数呈现一个消息框，它包含三个图标之一，一个标题，和一个格式化的消息。该消息可以包含根据你输入的命令格式化的变量。

    SprintfBox和MessageBox相似，但SprintfBox对显示的内容允许更多的弹性控制。

参数：

nType

指定显示在消息框中的图标类型。在该参数位置传递下列预定义的常量之一（显示Windows 95图标）：

INFORMATION信息

WARNING警告

SEVERE严重警告

szTitle

指定消息框标题。为显示缺省标题（“错误”） ，给该参数传递一个空字符串（””）。

szFormat

指定一个包含一个格式说明符的字符串，格式说明符是针对包含在消息中的每个参数的。

arg

指定包含在消息中的参数，至多可达10个。对消息中每个格式说明符必须有一个参数；每个参数类型必须和它各自的格式说明符相匹配。SprintfBox在下列情况下将产生一个编译错误或在运行时失败：

·指定多于十个格式说明符和参数：编译错误。

·参数数目和格式说明符数目不匹配。当一个说明符没有相应的参数，结果字符串将在说明符位置包括不可预测的字符。当参数多于说明符，多余的参数将被插入到结果字符串中。

·一个变量和它各自的格式说明符不匹配。结果字符串将在说明符位置包含不可预测字符。

返回值：

除非你使用本机的Windows 消息框风格（描述如下），返回值是没有意义的。

注解：

·该函数使用Microsoft Windows API MessageBox来创建消息框。消息框的OK按钮包含操作环境产生的文本。是操作环境而不是InstallShield确定消息框的大小和位置。

·熟悉Windows API的高级开发者可以通过在参数nType使用本机消息框风格常量来指定任何风格的消息框。查看你的操作环境编程手册中MessageBox 或WinMessageBox的说明。如果你使用任何本机消息框风格，InstallShiled SprintfBox函数将返回Windows API的返回值。因此，你必须在你的脚本中使用Windows API的返回值。

  例如，如果你传递 YES|NO|CANCEL作为第一个参数，SprintfBox消息框将有Yes,No和Cancel按钮。各个按钮返回值，如Windows API MessageBox定义，是6 (IDYES), 7 (IDNO), 和2 (IDCANCEL)。你必须在你的脚本中使用适当的常量值，作为数字或作为在你的脚本的声明区中定义为数字的常量。

·高级开发者可以直接使用MB_STYLE作为SprintfBox函数的第一个参数来代替常量SEVERE, WARNING或 INFORMATION。MB_STYLE的值列在Windows.h中。你可以给参数nType直接输入值，或可以使用#define 预处理程序指令来定义和该值联系的常量。

·当使用Windows消息框常量时注意下列问题：

· Windows MessageBox类型常量在Windows.h文件中声明，它不能被包括在一个InstallShield脚本中。当使用这些常量时，你必须在安装脚本的声明区定义它们（用#define）。赋给这些常量的值通常可以在由适当的Windows SDK或开发工具提供的一个包含文件中找到。对于Microsoft Visual C++，大多数常量可以在位于DevStudio\Vc\include文件夹的Windows.h文件中找到。

·Windows 和InstallShield消息框常量不能在一个安装中一起使用。如果一个InstallShield消息框常量和一个 Windows 消息框常量用一个或运算符组合，Windows 消息框常量将被忽略。

·一些Windows 消息框风格在一些Windows 平台不受支持。为确定一个特定的风格是否受安装确定的操作系统支持，咨询适当的Windows SDK。

4.15  Welcome

语法：Welcome (szTitle, nReserved);

说明：Welcome函数显示一个对话框来欢迎最终用户。

参数：

szTitle

指定该对话框的标题。为显示缺省标题（“欢迎”） ，给该参数传递一个空字符串。

nReserved

给该参数传递0。

返回值：

NEXT (1)：表明最终用户选择NEXT按钮。

BACK (12)：表明最终用户选择BACK按钮。

< 0：表明Welcome未能显示对话框。

注解：

·在一个过程脚本中，为使InstallShield可以在欢迎对话框的消息文本的第一段中插入产品名称，你必须在调用Welcome前调用SdProductName。（在一个基于事件的脚本中，在Begin事件前，SdProductName被自动调用，以PRODUCT_NAME字符串表入口为参数）。如果你不使用SdProductName来传递一个产品名称，InstallShield不能插入产品名称而是将插入一个附加的空格。

5  Sd对话框函数

    InstallShield提供一些Sd对话框函数，用户可自定义和显示。Sd对话框使用可以创建用户输入的对话框的特殊脚本定义函数来创建。然后该对话框根据所作选择返回值给脚本。

    Sd对话框有一个Cancel按钮，当它被选中时不返回一个CANCEL值。而是调用缺省的退出处理。

下面是所有有效的Sd对话框函数的列表：

s DialogSetInfo

改变由一些内部对话框函数呈现的对话框的显示元素。

s SdAskDestPath

呈现一个对话框，允许最终用户指定安装的一个目标位置。

s SdAskOptions

创建一个对话框，它比标准AskOptions函数更灵活。

s SdAskOptionsList

呈现一个对话框，允许最终用户选定和撤消选定一个列表中的项目。

s SdBitmap

在对话框中显示一个位图。

s SdComponentDialog

显示一个对话框，允许最终用户选择安装的组件和目标文件夹。

s SdComponentDialog2

显示一个对话框，允许最终用户选择要安装的文件夹、组件和子部件。

s SdComponentDialogAdv

显示一个对话框，允许最终用户选择安装的组件和目标文件夹。

s SdComponentMult

显示一个对话框，允许最终用户选择安装的组件和子部件。有关磁盘空间的附加信息也被提供来确定安装的最佳位置。

s SdComponentTree

显示一个有树形控制控件的对话框，允许最终用户选择安装的组件和子部件。有关磁盘空间的附加信息也被提供来确定安装的最佳位置。

s SdConfirmNewDir

提示用户确认文件夹的选择。

s SdConfirmRegistration

提示最终用户确认输入到由SdRegisterUser或SdRegisterUserEx呈现对话框中的信息。

s SdDisplayTopics

显示主题列表。

s SdExceptions

显示一个对话框，通知最终用户遇到一个共享、锁定（在使用中）或只读文件。

s SdFinish

显示一个对话框，通知最终用户安装完成并提供一个选项的选择，如是否要查看信息文件或运行一个应用程序。

s SdFinishEx

显示一个对话框，通知最终用户安装完成。

s SdFinishReboot

显示一个对话框，通知用户安装完成并提供一个重启Windows 和计算机选项的选择。

s SdInit

准备一个调用Sd对话框函数的安装。

s SdLicense

显示一个许可证协议并给最终用户一个接受或拒绝许可证条款的选项。

s SdLoadString

返回和一个指定资源ID相联系的字符串值。

s SdMakeName

创建一个自定义对话框的节名。该节名在向一个 .iss文件写或从一个.iss文件读时使用。.iss文件由 InstallShield Silent使用。

s SdOptionsButtons

显示一个有用户定义按钮的对话框，提供给最终用户不同选择。

s SdProductName

在脚本对话框的特定静态区中插入你的产品名。

s SdRegisterUser

显示一个可输入用户名和公司名的对话框。

s SdRegisterUserEx

显示一个对话框，最终用户可在里面输入用户姓名、公司名称和应用程序序列号。

s SdSelectFolder

呈现一个对话框，允许最终用户从程序文件夹列表中选择一个文件夹。

s SdSetupType

显示一个对话框，使最终用户能选择三种标准安装类型之一：典型、简易或自定义。

s SdSetupTypeEx

显示一个对话框，允许最终用户选择标准或自定义安装类型。

s SdShowAnyDialog

显示一个资源DLL的通用对话框。当用SdShowAnyDialog函数显示一个对话框时你不能从最终用户接受任何输入。

s SdShowDlgEdit1

显示一个对话框，它有一个单行的编辑区和其它静态控件。

s SdShowDlgEdit2

显示一个对话框，有两个单行的编辑区和其它静态控件。

s SdShowDlgEdit3

显示一个对话框，有三个单行的编辑区和其它静态控件。

s SdShowFileMods

呈现一个对话框，预览对文件的可能修改并允许最终用户同意修改、拒绝修改或要求将修改写到一个文件中。

s SdShowInfoList

在一个对话框中显示一个可滚动的消息列表。

s SdShowMsg

在一个小窗口中显示一个消息。

s SdStartCopy

呈现一个对话框，显示已经由最终用户指定的选项和设置。

s SdWelcome

显示一个通用欢迎。

s SdWelcomeMaint

显示一个在维护安装开始时使用的对话框。

5.1  DialogSetInfo

语法：DialogSetInfo (nInfoType, szInfoString, nParameter);

说明：DialogSetInfo函数修改下列在InstallShield对话框中显示的元件：

s 显示的图象；

s 得到最终用户选择的复选框的风格；

s 指示有效和所需磁盘空间值的精度。

    通过调用DialogSetInfo产生的修改对安装的剩余部分保持为有效或直到它们又被随后的对DialogSetInfo的调用修改。如果你的脚本在调用任何Sd对话框函数前调用DialogSetInfo，在 DialogSetInfo的调用前必须先调用SdInit。否则，对DialogSetInfo的调用无效。

参数：

nInfoType

指定要修改的显示特征。在该参数位置传递下列预定义的常量之一：

DLG_INFO_USEDECIMAL：缺省时，显示的指示组件大小、有效磁盘空间和所需磁盘空间的值被四舍五入到最近的KB或MB。下列对话框受该参数影响：ComponentDialog, SdComponentDialog, SdComponentDialog2, SdComponentDialogAdv 和SdComponentMult。

DLG_INFO_KUNITS：缺省时，显示的指示组件大小、有效磁盘空间和所需磁盘空间的值以KB为度量。传递该参数同时nParameter设置为FALSE时则以MB为度量显示这些值。下列对话框受该参数影响：SdComponentTree, ComponentDialog, SdComponentDialog, SdComponentDialog2, SdComponentDialogAdv 和SdComponentMult。

DLG_INFO_ALTIMAGE：指定一个显示在该对话框中的候选位图。如果nParameter设置为