Products - Icetips Utilities - SetupBuilder Class

SetupBuilder Class   (ITSetupBuilderClass)

The SetupBuilder Class has 22 methods (functions) that perform a variety of tasks related to SetupBuilder or installs. You can easily include these in your software (documentation that comes with the Utilities covers this in detail) The SetupBuilder class has two main functionalities.

First is to make it easy to copy files from a common install folder, such as "All Users\Application Data" to a local folder such as "User Name\Application Data" This is very important when installing on Windows Vista because the installer normally cannot install into user folders as it requires administrator access, which changes the user account.

The second is to compile SetupBuilder projects. This can be useful if you want to automate compiling your SetupBuilder project.

The following methods are used to copy installed files:

• SetGlobalCSIDL/SetLocalCSIDL

This sets the CSIDL location for the source and destination respectively when copying files from a common (global) location to a user specific (local) location.

• CopyTheFiles

This method copies all files and folders from the source folder to the destination folder. A partial path (PathString) is used to determine the full source path, i.e. it is appended to the CSIDL folder for both the source and the destination. For example if the CSIDL is CSIDL_COMMON_APPDATA, and the partial PathString is "Icetips Creative\Utilities" this would mean that the source folder is set to "C:\Documents and Settings\All Users\Application Data\Icetips Creative\Utilities" The same partial folder is appended to the destination CSIDL folder. The PathString is also used to update a registry key under HKCU\Software - in this case it would be "HKCU\Software\Icetips Creative\Utilities" with a value called FilesCopied. CopyTheFiles creates this key and value if it doesn't exist and sets FilesCopied to True. This method is used by the FinishTheInstall method which you would generally call before you access any files in your software to ensure that user data has been set up.

• SetPathString

The PathString contains the partial path that is used in CopyTheFiles to determine source and destination folders as well as the registry key to update.

• FinishInstall

This is a "do-it-all" method that takes the CSIDL values for the source and destination and the partial path string and copies the files and does all the work. This method is all you need to use to copy the data and set everything right. You would normally call this method before you do any file access in your program to ensure that all user data has been set up.

The following methods are used to compile SetupBuilder projects:

• CompileSBProject

Use this method to compile a SetupBuilder project. If you set the DestinationFolder property before you call this method the project will be compiled into that folder. If the folder does not exist it will be created. Note that this only works in SetupBuilder 6.5 build 2000 or later. In earlier builds this will be ignored and the default destination used, which is the location of the project file with a new folder created with the same name as the project file.

• CompileSBProject

Use this method to compile a SetupBuilder project. If you set the DestinationFolder property before you call this method the project will be compiled into that folder. If the folder does not exist it will be created. Note that this only works in SetupBuilder 6.5 build 2000 or later. In earlier builds this will be ignored and the default destination used, which is the location of the project file with a new folder created with the same name as the project file.

• AddCompilerVariable

This method can be used to pass values for compiler variables to your SetupBuilder project. This is limited to the amount of data that can be passed via the command line to the SetupBuilder compiler. Under Vista this is around 2K but under XP this should be close to 8K. This allows you to pass for example version number to user in the compile process. Note that passing the compiler variables to the project does NOT update the project, it simply instructs the compiler to use the values instead of the values in the project.

The demo application (UtilDemo.app) that is installed into the "Clarion\3rdParty\Examples\ITUtilities" folder contains a procedure called TestSetupBuilderClass that demonstrates how to use these methods to compile a SetupBuilder project as well as copy the files. This class is also documented starting on page 56 in the PDF documentation as of Beta 3.1 released on November 8, 2007.